@blamejs/core 0.4.23 → 0.4.24

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.23** (2026-04-30) — b.mail.dkim signing + calendar invites
 - **0.4.22** (2026-04-30) — b.mail attachments + inline images + plain/HTML alternatives
 - **0.4.21** (2026-04-30) — b.queue: repeat-in-queue (cron) + parent-child Flows
 - **0.4.20** (2026-04-30) — b.queue + b.jobs: priority, rate-limit, progress

package/lib/object-store/sigv4.js

@@ -208,6 +208,135 @@ function _request(method, url, headers, body, opts) {
   });
 }
 
+// ---- Multipart-upload constants ----
+
+// S3 spec floor for non-final part size. Below this the API rejects
+// CompleteMultipartUpload with EntityTooSmall. The framework refuses
+// configurations below this floor at create() time so operators don't
+// see surprising failures only on large uploads.
+var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
+// S3 spec ceiling on part count. CompleteMultipartUpload rejects
+// uploads with more than 10000 parts.
+var MAX_PARTS = 10000;
+// Auto-multipart trigger: buffered bodies under this stay single-PUT.
+// Streams always go multipart since size isn't known up-front.
+var DEFAULT_MULTIPART_THRESHOLD_BYTES = 64 * 1024 * 1024;
+// Conservative default part size — large enough to keep round-trip
+// overhead small relative to payload, small enough to fit comfortably
+// in a 4-way-concurrent upload's memory footprint.
+var DEFAULT_PART_SIZE_BYTES = 16 * 1024 * 1024;
+var DEFAULT_PART_CONCURRENCY = 4;
+
+// ---- SSE option handling ----
+
+function _resolveSseHeaders(sse) {
+  if (sse === undefined || sse === null) return null;
+  var type;
+  var keyId = null;
+  if (typeof sse === "string") {
+    type = sse;
+  } else if (sse && typeof sse === "object") {
+    type = sse.type;
+    keyId = sse.keyId || null;
+  } else {
+    throw _err("INVALID_SSE",
+      "opts.sse must be a string ('AES256' | 'aws:kms') or " +
+      "{ type, keyId }, got " + typeof sse, true);
+  }
+  if (type !== "AES256" && type !== "aws:kms") {
+    throw _err("INVALID_SSE",
+      "opts.sse type must be 'AES256' or 'aws:kms', got '" + type + "'", true);
+  }
+  var h = { "x-amz-server-side-encryption": type };
+  if (type === "aws:kms" && keyId) {
+    h["x-amz-server-side-encryption-aws-kms-key-id"] = String(keyId);
+  }
+  return { type: type, keyId: keyId, headers: h };
+}
+
+function _verifySseResponse(sseRequested, resHeaders) {
+  // Operators who specified an SSE policy expect the bucket / object to
+  // honor it. If the server silently dropped the header (mis-configured
+  // bucket policy, unsupported endpoint, etc.) the request looks like a
+  // success but the at-rest data is unencrypted. Surface this as a
+  // hard failure rather than a silent compliance hole.
+  if (!sseRequested) return;
+  var got = resHeaders["x-amz-server-side-encryption"];
+  if (!got) {
+    throw _err("SSE_NOT_APPLIED",
+      "opts.sse was '" + sseRequested.type + "' but server did not " +
+      "apply server-side encryption (no x-amz-server-side-encryption " +
+      "response header)", true);
+  }
+  if (got !== sseRequested.type) {
+    throw _err("SSE_MISMATCH",
+      "opts.sse requested '" + sseRequested.type + "' but server " +
+      "applied '" + got + "'", true);
+  }
+}
+
+// ---- Multipart helpers ----
+
+// Build the CompleteMultipartUpload request body. Parts must be in
+// ascending PartNumber order. ETags from S3 include surrounding
+// quotes — preserve them exactly.
+function _buildCompleteMultipartXml(parts) {
+  var body = "<CompleteMultipartUpload>";
+  for (var i = 0; i < parts.length; i++) {
+    body += "<Part>";
+    body += "<PartNumber>" + parts[i].partNumber + "</PartNumber>";
+    body += "<ETag>" + parts[i].etag + "</ETag>";
+    body += "</Part>";
+  }
+  body += "</CompleteMultipartUpload>";
+  return body;
+}
+
+// Read a Readable stream into fixed-size buffers. Yields one Buffer
+// per part (size <= partSize). The final part may be smaller. The
+// stream is consumed exactly once.
+async function _readStreamParts(readable, partSize) {
+  var parts = [];
+  var pending = [];
+  var pendingBytes = 0;
+  for await (var chunk of readable) {
+    var buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    pending.push(buf);
+    pendingBytes += buf.length;
+    while (pendingBytes >= partSize) {
+      var combined = Buffer.concat(pending, pendingBytes);
+      parts.push(combined.slice(0, partSize));
+      var leftover = combined.slice(partSize);
+      pending = leftover.length > 0 ? [leftover] : [];
+      pendingBytes = leftover.length;
+    }
+  }
+  if (pendingBytes > 0) {
+    parts.push(Buffer.concat(pending, pendingBytes));
+  }
+  return parts;
+}
+
+// Run an array of async tasks with bounded parallelism. Preserves
+// result order by index.
+async function _bounded(items, concurrency, runner) {
+  var results = new Array(items.length);
+  var i = 0;
+  async function worker() {
+    while (true) {
+      var idx = i++;
+      if (idx >= items.length) return;
+      results[idx] = await runner(items[idx], idx);
+    }
+  }
+  var workers = [];
+  for (var w = 0; w < Math.min(concurrency, items.length); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+
 // ---- Public adapter factory ----
 
 function create(config) {
@@ -220,6 +349,30 @@ function create(config) {
   var endpoint = config.endpoint || ("https://s3." + config.region + ".amazonaws.com");
   if (endpoint.endsWith("/")) endpoint = endpoint.slice(0, -1);
   var pathStyle = !!(config.pathStyle || config.forcePathStyle);
+
+  var partSize = config.partSizeBytes != null
+    ? config.partSizeBytes
+    : DEFAULT_PART_SIZE_BYTES;
+  if (typeof partSize !== "number" || !isFinite(partSize) || partSize < MIN_PART_SIZE_BYTES) {
+    throw _err("INVALID_CONFIG",
+      "sigv4: partSizeBytes must be a number >= " + MIN_PART_SIZE_BYTES +
+      " (S3 minimum part size), got " + partSize, true);
+  }
+  var multipartThreshold = config.multipartThresholdBytes != null
+    ? config.multipartThresholdBytes
+    : DEFAULT_MULTIPART_THRESHOLD_BYTES;
+  if (typeof multipartThreshold !== "number" || !isFinite(multipartThreshold) || multipartThreshold < 0) {
+    throw _err("INVALID_CONFIG",
+      "sigv4: multipartThresholdBytes must be a non-negative finite number, got " +
+      multipartThreshold, true);
+  }
+  var partConcurrency = config.partConcurrency != null
+    ? config.partConcurrency
+    : DEFAULT_PART_CONCURRENCY;
+  if (typeof partConcurrency !== "number" || partConcurrency < 1 || !isFinite(partConcurrency)) {
+    throw _err("INVALID_CONFIG",
+      "sigv4: partConcurrency must be a positive finite number, got " + partConcurrency, true);
+  }
   // HTTPS-only by default — AWS S3, R2, MinIO-over-https. Operators with
   // an internal cleartext S3-compatible endpoint (test fixtures, local
   // dev MinIO) opt in via config.allowedProtocols.
@@ -274,19 +427,150 @@ function create(config) {
   }
 
   function put(key, body, opts) {
-    var url = _keyToUrl(key);
+    opts = opts || {};
+    var sseRequested = _resolveSseHeaders(opts.sse);
+    // Streams always go multipart — size isn't known up-front. Buffers
+    // dispatch to multipart when they exceed the threshold; operators
+    // can force the single-PUT path with `multipart: false` (small
+    // bodies in unit tests, or to keep the request count to one).
+    var isStream = body && typeof body === "object" && typeof body.pipe === "function";
+    if (isStream) {
+      if (opts.multipart === false) {
+        return Promise.reject(_err("STREAM_REQUIRES_MULTIPART",
+          "put(stream) requires multipart upload (set opts.multipart !== false)", true));
+      }
+      return _multipartPut(key, body, opts, sseRequested);
+    }
     var buf = Buffer.isBuffer(body) ? body : Buffer.from(typeof body === "string" ? body : "", "utf8");
+    if (opts.multipart !== false &&
+        (opts.multipart === true || buf.length > multipartThreshold)) {
+      return _multipartPut(key, buf, opts, sseRequested);
+    }
+    return _singlePut(key, buf, opts, sseRequested);
+  }
+
+  function _singlePut(key, buf, opts, sseRequested) {
+    var url = _keyToUrl(key);
     var payloadHash = sha256Hex(buf);
-    var contentType = (opts && opts.contentType) || "application/octet-stream";
-    var headers = _makeSigned("PUT", url, payloadHash, {
+    var contentType = opts.contentType || "application/octet-stream";
+    var extra = {
       "Content-Type":   contentType,
       "Content-Length": String(buf.length),
-    });
+    };
+    if (sseRequested) Object.assign(extra, sseRequested.headers);
+    var headers = _makeSigned("PUT", url, payloadHash, extra);
     return _request("PUT", url, headers, buf, reqOpts).then(function (res) {
+      _verifySseResponse(sseRequested, res.headers);
       return { size: buf.length, etag: res.headers.etag };
     });
   }
 
+  async function _multipartPut(key, body, opts, sseRequested) {
+    var contentType = opts.contentType || "application/octet-stream";
+
+    // Slice into parts. For Buffers we slice up-front; for streams we
+    // read sequentially into part-sized buffers (memory bounded).
+    var parts;
+    if (Buffer.isBuffer(body)) {
+      parts = [];
+      for (var off = 0; off < body.length; off += partSize) {
+        parts.push(body.slice(off, Math.min(off + partSize, body.length)));
+      }
+      // Edge case: empty buffer → one zero-length part. S3 rejects
+      // multipart with zero parts; rather than handling this corner
+      // we route empty buffers through single-PUT instead.
+      if (parts.length === 0) parts = [Buffer.alloc(0)];
+    } else {
+      parts = await _readStreamParts(body, partSize);
+      if (parts.length === 0) parts = [Buffer.alloc(0)];
+    }
+    if (parts.length > MAX_PARTS) {
+      throw _err("TOO_MANY_PARTS",
+        "multipart upload would require " + parts.length + " parts " +
+        "(S3 max " + MAX_PARTS + "); increase partSizeBytes", true);
+    }
+
+    // 1. Initiate
+    var url = _keyToUrl(key);
+    var initiateUrl = new URL(url.href);
+    initiateUrl.searchParams.set("uploads", "");
+    var initiateExtra = {
+      "Content-Type":   contentType,
+      "Content-Length": "0",
+    };
+    if (sseRequested) Object.assign(initiateExtra, sseRequested.headers);
+    var initiateHeaders = _makeSigned("POST", initiateUrl, sha256Hex(Buffer.alloc(0)), initiateExtra);
+    var initRes = await _request("POST", initiateUrl, initiateHeaders, Buffer.alloc(0), reqOpts);
+    _verifySseResponse(sseRequested, initRes.headers);
+    var initDoc = safeXml.parse(initRes.body, LIST_PARSE_OPTS);
+    var uploadId = initDoc.InitiateMultipartUploadResult &&
+      initDoc.InitiateMultipartUploadResult.UploadId;
+    if (!uploadId) {
+      throw _err("MULTIPART_INIT_FAILED",
+        "S3 InitiateMultipartUpload response missing UploadId", false);
+    }
+
+    var totalSize = 0;
+    var uploadedEtags;
+
+    try {
+      // 2. Upload parts (concurrency-bounded)
+      uploadedEtags = await _bounded(parts, partConcurrency, async function (partBuf, idx) {
+        var partNumber = idx + 1;
+        var partUrl = new URL(url.href);
+        partUrl.searchParams.set("partNumber", String(partNumber));
+        partUrl.searchParams.set("uploadId", uploadId);
+        var partHeaders = _makeSigned("PUT", partUrl, sha256Hex(partBuf), {
+          "Content-Length": String(partBuf.length),
+        });
+        var partRes = await _request("PUT", partUrl, partHeaders, partBuf, reqOpts);
+        if (!partRes.headers.etag) {
+          throw _err("MULTIPART_PART_FAILED",
+            "UploadPart response missing ETag for part " + partNumber, false);
+        }
+        totalSize += partBuf.length;
+        return { partNumber: partNumber, etag: partRes.headers.etag };
+      });
+
+      // 3. Complete
+      var completeUrl = new URL(url.href);
+      completeUrl.searchParams.set("uploadId", uploadId);
+      var completeBody = Buffer.from(_buildCompleteMultipartXml(uploadedEtags), "utf8");
+      var completeHeaders = _makeSigned("POST", completeUrl, sha256Hex(completeBody), {
+        "Content-Type":   "application/xml",
+        "Content-Length": String(completeBody.length),
+      });
+      var completeRes = await _request("POST", completeUrl, completeHeaders, completeBody, reqOpts);
+      // S3 may return 200 OK with an error body on CompleteMultipartUpload —
+      // surface that as a hard error rather than a silent success.
+      var completeDoc = safeXml.parse(completeRes.body, LIST_PARSE_OPTS);
+      if (completeDoc.Error) {
+        throw _err("MULTIPART_COMPLETE_FAILED",
+          "CompleteMultipartUpload returned error: " +
+          (completeDoc.Error.Code || "unknown") + " " +
+          (completeDoc.Error.Message || ""), false);
+      }
+      // SSE was already verified on the InitiateMultipartUpload
+      // response — that's the request that establishes the upload's
+      // encryption policy server-side. The CompleteMultipartUpload
+      // response may or may not echo the header depending on vendor;
+      // re-verifying here would double-fault on otherwise-fine setups.
+      var result = completeDoc.CompleteMultipartUploadResult || {};
+      return { size: totalSize, etag: result.ETag || completeRes.headers.etag, multipart: true };
+    } catch (e) {
+      // Abort cleans up server-side storage for the partial upload.
+      // Failures here are silently swallowed — the caller's original
+      // error is what they need to see, not a secondary cleanup error.
+      try {
+        var abortUrl = new URL(url.href);
+        abortUrl.searchParams.set("uploadId", uploadId);
+        var abortHeaders = _makeSigned("DELETE", abortUrl, sha256Hex(Buffer.alloc(0)));
+        await _request("DELETE", abortUrl, abortHeaders, null, reqOpts);
+      } catch (_e) { /* primary error wins */ }
+      throw e;
+    }
+  }
+
   function get(key) {
     var url = _keyToUrl(key);
     var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.23",
+  "version": "0.4.24",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",