@nextlyhq/storage-vercel-blob 0.0.2-alpha.60 → 0.0.2-alpha.64

package/dist/index.cjs

@@ -4,7 +4,7 @@ var blob = require('@vercel/blob');
 
 // src/adapter.ts
 
-// ../nextly/dist/chunk-A6VGQLBN.mjs
+// ../nextly/dist/chunk-HJ5IQPOY.mjs
 function isDbError(err) {
   if (!err || typeof err !== "object") return false;
   const obj = err;
@@ -43,6 +43,21 @@ var NEXTLY_ERROR_STATUS = {
   MIME_BLOCKED: 415,
   MIME_NOT_ALLOWED: 415,
   SIZE_EXCEEDED: 413,
+  // A stored object exceeded the cap a READ was given, which is a different
+  // question from SIZE_EXCEEDED above: that one refuses an upload the caller
+  // is sending, this one refuses to buffer an object already stored. Kept
+  // apart so a caller discriminating on the code cannot match both.
+  STORAGE_READ_TOO_LARGE: 413,
+  // A stored object did not answer within the deadline the read was given. 504
+  // rather than 500 because the failure is the BACKEND not answering, and a
+  // caller can act on that difference: a gateway timeout is worth retrying, an
+  // internal error is not.
+  STORAGE_READ_TIMEOUT: 504,
+  // The store answered, and answered badly. 502 rather than 500 because the
+  // fault is UPSTREAM of this process: a caller can retry it, and an operator
+  // reading the log needs to look at the bucket rather than at this service.
+  // Distinct from the timeout above, which never got an answer at all.
+  STORAGE_READ_UNREACHABLE: 502,
   MAGIC_BYTE_MISMATCH: 400,
   SVG_SANITIZATION_FAILED: 400,
   UNSUPPORTED_FOR_BACKEND: 415,
@@ -82,11 +97,26 @@ var NEXTLY_ERROR_STATUS = {
   // Plugin platform — a declared admin.clientConfig that cannot be delivered
   // to the browser, refused at boot rather than serialized mangled.
   NEXTLY_PLUGIN_CLIENT_CONFIG_INVALID: 500,
+  // Plugin platform — a contributed admin widget that cannot be delivered to
+  // the browser. Refused at boot because it is serialized into the ONE
+  // `/api/admin-meta/workspace` payload: a value `JSON.stringify` throws on
+  // fails that request for every admin, not just the widget's own card.
+  NEXTLY_PLUGIN_ADMIN_WIDGET_INVALID: 500,
   // Plugin platform (P0) — boot-time plugin dependency/version resolution.
   PLUGIN_RESOLUTION_ERROR: 500,
   // Plugin platform (P4) — contributes.routes collection (D25).
   NEXTLY_ROUTE_COLLISION: 409,
-  NEXTLY_ROUTE_INVALID_PATH: 400
+  NEXTLY_ROUTE_INVALID_PATH: 400,
+  // An email transport whose library is an optional peer dependency the host
+  // has not installed. 503 rather than 500: the request is not malformed and
+  // nothing is broken, the install simply cannot carry it out yet, and the
+  // remedy is one command on the server rather than a change by the caller.
+  NEXTLY_EMAIL_TRANSPORT_UNAVAILABLE: 503,
+  // The tooling that compiles `nextly.config.ts` is an optional peer the host
+  // has not installed. 503 rather than 500 for the same reason as the mail
+  // transport above: nothing is broken and the request is not malformed, the
+  // install simply cannot carry it out until one command is run.
+  NEXTLY_CONFIG_TOOLING_UNAVAILABLE: 503
 };
 var CANONICAL_CODE_FOR_STATUS = [
   "VALIDATION_ERROR",
@@ -263,7 +293,7 @@ var NextlyError = class _NextlyError extends Error {
   static notFound(opts) {
     return new _NextlyError({
       code: "NOT_FOUND",
-      publicMessage: "Not found.",
+      publicMessage: opts?.message ?? "Not found.",
       cause: opts?.cause,
       logContext: opts?.logContext
     });
@@ -414,6 +444,523 @@ var NextlyError = class _NextlyError extends Error {
   }
 };
 
+// ../nextly/dist/chunk-W77AQUUQ.mjs
+var StorageReadTooLargeError = class extends NextlyError {
+  constructor(path, maxBytes, size) {
+    super({
+      code: "STORAGE_READ_TOO_LARGE",
+      publicMessage: "The stored file is larger than the limit for this read.",
+      logContext: {
+        path,
+        maxBytes,
+        ...size === void 0 ? {} : { size }
+      }
+    });
+    this.path = path;
+    this.maxBytes = maxBytes;
+    this.size = size;
+  }
+};
+
+// ../nextly/dist/chunk-C2VHLQKK.mjs
+var IPV4_RE = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
+var PRIVATE_IPV4_CIDRS = [
+  "0.0.0.0/8",
+  // RFC1122 "this network" / wildcard
+  "10.0.0.0/8",
+  // RFC1918
+  "100.64.0.0/10",
+  // RFC6598 CGNAT
+  "127.0.0.0/8",
+  // RFC1122 loopback
+  "169.254.0.0/16",
+  // RFC3927 link-local + AWS/GCP metadata
+  "172.16.0.0/12",
+  // RFC1918
+  "192.0.0.0/24",
+  // RFC6890 IETF protocol assignments
+  "192.0.2.0/24",
+  // RFC5737 documentation
+  "192.168.0.0/16",
+  // RFC1918
+  "198.18.0.0/15",
+  // RFC2544 benchmarking
+  "198.51.100.0/24",
+  // RFC5737 documentation
+  "203.0.113.0/24",
+  // RFC5737 documentation
+  "224.0.0.0/4",
+  // RFC5771 multicast
+  "240.0.0.0/4"
+  // RFC1112 reserved
+];
+var CLOUD_METADATA_HOSTS = /* @__PURE__ */ new Set([
+  "metadata.google.internal",
+  "metadata.googleapis.com",
+  "metadata"
+  // GCP short form
+]);
+var ExternalUrlError = class extends NextlyError {
+  constructor(message, url) {
+    super({
+      code: "EXTERNAL_URL_BLOCKED",
+      publicMessage: message,
+      logContext: { url }
+    });
+    this.url = url;
+    this.name = "ExternalUrlError";
+  }
+};
+async function validateExternalUrl(rawUrl, options = {}) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new ExternalUrlError("Invalid URL", rawUrl);
+  }
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  const isLocalhostHostname = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+  const baseProtocols = options.allowedProtocols ?? ["https:"];
+  const protocols = options.allowLocalhost && isLocalhostHostname ? [...baseProtocols, "http:"] : baseProtocols;
+  if (!protocols.includes(parsed.protocol)) {
+    throw new ExternalUrlError(
+      `Protocol ${parsed.protocol} not allowed (allowed: ${protocols.join(", ")})`,
+      rawUrl
+    );
+  }
+  if (CLOUD_METADATA_HOSTS.has(hostname)) {
+    throw new ExternalUrlError(
+      `Cloud-metadata hostname rejected: ${parsed.hostname}`,
+      rawUrl
+    );
+  }
+  if (IPV4_RE.test(hostname)) {
+    if (!isPublicIpv4(
+      hostname,
+      options.allowLocalhost === true && hostname === "127.0.0.1"
+    )) {
+      throw new ExternalUrlError(
+        `Resolved to non-public IP: ${hostname}`,
+        rawUrl
+      );
+    }
+    return { url: parsed, pinnedIp: hostname, family: 4 };
+  }
+  if (hostname.includes(":")) {
+    if (!isPublicIpv6(
+      hostname,
+      options.allowLocalhost === true && hostname === "::1"
+    )) {
+      throw new ExternalUrlError(
+        `Resolved to non-public IP: ${hostname}`,
+        rawUrl
+      );
+    }
+    return { url: parsed, pinnedIp: hostname, family: 6 };
+  }
+  const { lookup } = await import('dns/promises');
+  let addresses;
+  try {
+    addresses = await lookup(hostname, { all: true });
+  } catch (err) {
+    throw new ExternalUrlError(
+      `DNS lookup failed: ${err.message}`,
+      rawUrl
+    );
+  }
+  if (addresses.length === 0) {
+    throw new ExternalUrlError("No IPs returned for host", rawUrl);
+  }
+  for (const { address, family } of addresses) {
+    const allow = options.allowLocalhost === true && isLocalhostHostname && family === 4;
+    const ok = family === 4 ? isPublicIpv4(address, allow) : isPublicIpv6(address, allow);
+    if (!ok) {
+      throw new ExternalUrlError(
+        `Resolved to non-public IP: ${address}`,
+        rawUrl
+      );
+    }
+  }
+  const first = addresses[0];
+  return {
+    url: parsed,
+    pinnedIp: first.address,
+    family: first.family === 6 ? 6 : 4
+  };
+}
+var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var SafeFetchError = class extends NextlyError {
+  constructor(message, url, reason, status) {
+    super({
+      code: "EXTERNAL_REQUEST_FAILED",
+      publicMessage: message,
+      logContext: { url, reason }
+    });
+    this.url = url;
+    this.reason = reason;
+    this.status = status;
+    this.name = "SafeFetchError";
+  }
+};
+function createPinnedLookup(ip, family) {
+  return (_hostname, options, callback) => {
+    if (options && options.all) {
+      callback(null, [{ address: ip, family }]);
+    } else {
+      callback(null, ip, family);
+    }
+  };
+}
+async function safeFetch(rawUrl, options = {}) {
+  const {
+    allowLocalhost,
+    allowedProtocols,
+    method,
+    headers,
+    body,
+    signal,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES,
+    timeoutMs = DEFAULT_TIMEOUT_MS
+  } = options;
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(signal?.reason);
+  if (signal) {
+    if (signal.aborted) controller.abort(signal.reason);
+    else signal.addEventListener("abort", forwardAbort, { once: true });
+  }
+  const timer = setTimeout(
+    () => controller.abort(
+      new SafeFetchError(`Request exceeded ${timeoutMs}ms`, rawUrl, "timeout")
+    ),
+    timeoutMs
+  );
+  try {
+    const validated = await abortable(
+      validateExternalUrl(rawUrl, { allowLocalhost, allowedProtocols }),
+      controller.signal
+    );
+    return await pinnedFetch(validated, {
+      method,
+      headers,
+      body,
+      signal: controller.signal,
+      maxResponseBytes
+    });
+  } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener("abort", forwardAbort);
+  }
+}
+function abortError(signal) {
+  const reason = signal.reason;
+  if (reason instanceof Error) return reason;
+  return new DOMException("The operation was aborted", "AbortError");
+}
+function abortable(promise, signal) {
+  if (signal.aborted) return Promise.reject(abortError(signal));
+  let onAbort;
+  const aborted = new Promise((_resolve, reject) => {
+    onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  return Promise.race([promise, aborted]).finally(
+    () => signal.removeEventListener("abort", onAbort)
+  );
+}
+async function pinnedFetch(validated, init) {
+  const { url, pinnedIp, family } = validated;
+  const httpMod = url.protocol === "https:" ? await import('https') : await import('http');
+  const zlib = await import('zlib');
+  const lookup = createPinnedLookup(pinnedIp, family);
+  const outHeaders = toOutgoingHeaders(init.headers);
+  if (init.body != null) {
+    delete outHeaders["transfer-encoding"];
+    outHeaders["content-length"] = String(
+      typeof init.body === "string" ? Buffer.byteLength(init.body) : init.body.byteLength
+    );
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    const failure = (err) => init.signal.aborted ? abortError(init.signal) : err;
+    const req = httpMod.request(
+      url,
+      {
+        method: init.method ?? "GET",
+        headers: outHeaders,
+        lookup,
+        // Fresh socket per request so a pooled connection can't reuse a
+        // differently-resolved address, and so the pinned lookup always runs.
+        agent: false,
+        // The combined deadline/caller signal aborts the request in flight.
+        signal: init.signal
+      },
+      (res) => {
+        const chunks = [];
+        let received = 0;
+        res.on("data", (chunk) => {
+          received += chunk.length;
+          if (received > init.maxResponseBytes) {
+            res.destroy();
+            req.destroy();
+            settle(
+              () => reject(
+                new SafeFetchError(
+                  `Response body exceeded ${init.maxResponseBytes} bytes`,
+                  url.href,
+                  "response-too-large",
+                  res.statusCode
+                )
+              )
+            );
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on("end", () => {
+          const decoded = decodeBody(
+            Buffer.concat(chunks),
+            res.headers["content-encoding"],
+            zlib,
+            init.maxResponseBytes,
+            url.href,
+            res.statusCode
+          );
+          if (decoded instanceof SafeFetchError) {
+            settle(() => reject(decoded));
+            return;
+          }
+          settle(
+            () => resolve(toWhatwgResponse(res, decoded.body, decoded.decoded))
+          );
+        });
+        res.on("error", (err) => settle(() => reject(failure(err))));
+      }
+    );
+    req.on("error", (err) => settle(() => reject(failure(err))));
+    if (!req.destroyed) {
+      if (init.body != null) req.write(init.body);
+      req.end();
+    }
+  });
+}
+function toOutgoingHeaders(headers) {
+  const out = {};
+  if (!headers) return out;
+  const add = (rawKey, value) => {
+    const key = rawKey.toLowerCase();
+    if (key === "host") return;
+    const existing = out[key];
+    out[key] = existing === void 0 ? value : [].concat(existing, value);
+  };
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => add(key, value));
+  } else if (Array.isArray(headers)) {
+    for (const [key, value] of headers) add(key, value);
+  } else {
+    for (const [key, value] of Object.entries(headers)) add(key, value);
+  }
+  return out;
+}
+function toWhatwgResponse(res, body, stripContentHeaders) {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(res.headers)) {
+    if (value == null) continue;
+    const lower = key.toLowerCase();
+    if (stripContentHeaders && (lower === "content-encoding" || lower === "content-length")) {
+      continue;
+    }
+    const values = Array.isArray(value) ? value : [value];
+    for (const v of values) {
+      try {
+        headers.append(key, v);
+      } catch {
+      }
+    }
+  }
+  const raw = res.statusCode ?? 502;
+  const status = raw >= 200 && raw <= 599 ? raw : 502;
+  const nullBody = status === 204 || status === 205 || status === 304;
+  const bytes = new Uint8Array(body.byteLength);
+  bytes.set(body);
+  return new Response(nullBody ? null : bytes, {
+    status,
+    statusText: res.statusMessage ?? "",
+    headers
+  });
+}
+function decodeBody(buf, encoding, zlib, cap, url, status) {
+  if (!encoding) return { body: buf, decoded: false };
+  if (buf.length === 0) return { body: buf, decoded: true };
+  const layers = encoding.split(",").map((e) => e.trim().toLowerCase()).filter(Boolean);
+  const opts = { maxOutputLength: cap };
+  let current = buf;
+  let decoded = false;
+  try {
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const enc = layers[i];
+      if (enc === "identity") continue;
+      if (enc === "gzip" || enc === "x-gzip") {
+        current = zlib.gunzipSync(current, opts);
+      } else if (enc === "br") {
+        current = zlib.brotliDecompressSync(current, opts);
+      } else if (enc === "deflate") {
+        try {
+          current = zlib.inflateSync(current, opts);
+        } catch (inflateErr) {
+          if (errorCode(inflateErr) === "ERR_BUFFER_TOO_LARGE")
+            throw inflateErr;
+          current = zlib.inflateRawSync(current, opts);
+        }
+      } else {
+        if (decoded) {
+          return new SafeFetchError(
+            `Cannot fully decode content-encoding "${encoding}"`,
+            url,
+            "decode-failed",
+            status
+          );
+        }
+        return { body: buf, decoded: false };
+      }
+      decoded = true;
+    }
+    return { body: current, decoded };
+  } catch (err) {
+    const tooLarge = errorCode(err) === "ERR_BUFFER_TOO_LARGE";
+    return new SafeFetchError(
+      tooLarge ? `Decoded ${encoding} response body exceeded the size cap` : `Failed to decode ${encoding} response body`,
+      url,
+      tooLarge ? "response-too-large" : "decode-failed",
+      status
+    );
+  }
+}
+function errorCode(err) {
+  if (err != null && typeof err === "object" && "code" in err) {
+    const code = err.code;
+    return typeof code === "string" ? code : void 0;
+  }
+  return void 0;
+}
+function ipv4ToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let acc = 0;
+  for (const p of parts) {
+    const n = Number(p);
+    if (!Number.isInteger(n) || n < 0 || n > 255) return null;
+    acc = acc << 8 | n;
+  }
+  return acc >>> 0;
+}
+function isIpv4InCidr(intIp, cidr) {
+  const [addr, prefixRaw] = cidr.split("/");
+  const intCidr = ipv4ToInt(addr);
+  if (intCidr === null) return false;
+  const prefix = Number(prefixRaw);
+  if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false;
+  const mask = prefix === 0 ? 0 : -1 >>> 32 - prefix << 32 - prefix;
+  return (intIp & mask) >>> 0 === (intCidr & mask) >>> 0;
+}
+function isPublicIpv4(addr, allowLoopback) {
+  const intIp = ipv4ToInt(addr);
+  if (intIp === null) return false;
+  if (allowLoopback && addr === "127.0.0.1") return true;
+  for (const cidr of PRIVATE_IPV4_CIDRS) {
+    if (isIpv4InCidr(intIp, cidr)) return false;
+  }
+  return true;
+}
+function mappedIpv4(lower) {
+  const dotted = lower.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (dotted) return dotted[1];
+  const hex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    return [hi >> 8, hi & 255, lo >> 8, lo & 255].join(".");
+  }
+  return null;
+}
+function isPublicIpv6(addr, allowLoopback) {
+  const lower = addr.toLowerCase();
+  if (allowLoopback && lower === "::1") return true;
+  const mapped = mappedIpv4(lower);
+  if (mapped) {
+    return isPublicIpv4(mapped, allowLoopback);
+  }
+  if (lower === "::" || lower === "::1") return false;
+  const firstHextet = lower.split(":")[0] || "";
+  if (firstHextet.startsWith("fc") || firstHextet.startsWith("fd"))
+    return false;
+  if (firstHextet.startsWith("fe8") || firstHextet.startsWith("fe9"))
+    return false;
+  if (firstHextet.startsWith("fea") || firstHextet.startsWith("feb"))
+    return false;
+  if (firstHextet.startsWith("ff")) return false;
+  return true;
+}
+async function fetchStoredBytes(url, context, label, options, signal) {
+  let response;
+  try {
+    response = await safeFetch(url, {
+      ...options?.maxBytes === void 0 ? {} : { maxResponseBytes: options.maxBytes },
+      /*
+       * A caller's signal REPLACES the deadline rather than joining it.
+       *
+       * These adapters look the object's address up before fetching it, and
+       * that lookup can stall too. Starting a fresh timer here would give the
+       * fetch its own full budget on top of however long the lookup took, so a
+       * read could outlive the deadline the caller was told applied — by
+       * roughly double. One signal begun before the lookup governs both phases.
+       */
+      ...signal !== void 0 ? { signal } : options?.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+    });
+  } catch (error) {
+    const verdict = classifyFetchFailure(error);
+    if (verdict === "absent") return null;
+    if (verdict === "oversized") {
+      throw new StorageReadTooLargeError(
+        context,
+        resolveReadBounds(options).maxBytes
+      );
+    }
+    throw error;
+  }
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw NextlyError.internal({
+      logContext: {
+        service: label,
+        path: context,
+        status: response.status,
+        statusText: response.statusText
+      }
+    });
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+function classifyFetchFailure(error) {
+  if (!(error instanceof SafeFetchError)) return "unknown";
+  if (error.status === 404) return "absent";
+  const successful = error.status !== void 0 && error.status >= 200 && error.status < 300;
+  return error.reason === "response-too-large" && successful ? "oversized" : "unknown";
+}
+var DEFAULT_READ_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+var DEFAULT_READ_MAX_BYTES = DEFAULT_MAX_RESPONSE_BYTES;
+function resolveReadBounds(options) {
+  return {
+    maxBytes: options?.maxBytes ?? DEFAULT_READ_MAX_BYTES,
+    timeoutMs: options?.timeoutMs ?? DEFAULT_READ_TIMEOUT_MS
+  };
+}
+
 // src/adapter.ts
 var VercelBlobStorageAdapter = class {
   /**
@@ -552,6 +1099,48 @@ var VercelBlobStorageAdapter = class {
       return false;
     }
   }
+  /**
+   * Read a stored blob back as bytes, or `null` when it is not there.
+   *
+   * A NETWORK round trip, unlike the local adapter's disk read, because the
+   * bytes live on Vercel's CDN and there is no other way to reach them. That
+   * cost is the reason a caller serving these from its own origin has to cache:
+   * the privacy rule that forces same-origin serving does not also make the
+   * fetch free, and an uncached proxy pays it on every request.
+   *
+   * The URL is taken from `head` rather than assembled from `filePath`,
+   * because a blob's address is issued by the service — it carries a random
+   * suffix this adapter never chose — so deriving one here would be guessing at
+   * a string another system owns.
+   *
+   * `null` for a missing blob rather than a throw, matching {@link exists}.
+   *
+   * @param filePath - Blob path/key
+   * @returns The blob's bytes, or `null` when it does not exist
+   */
+  async read(filePath, options) {
+    const deadline = AbortSignal.timeout(
+      options?.timeoutMs ?? DEFAULT_READ_TIMEOUT_MS
+    );
+    let target;
+    try {
+      const meta = await blob.head(filePath, {
+        token: this.resolvedConfig.token,
+        abortSignal: deadline
+      });
+      target = meta.downloadUrl ?? meta.url;
+    } catch (error) {
+      if (error instanceof blob.BlobNotFoundError) return null;
+      throw error;
+    }
+    return await fetchStoredBytes(
+      target,
+      filePath,
+      "Vercel Blob",
+      options,
+      deadline
+    );
+  }
   /**
    * Get public URL for Vercel Blob file.
    *