@sproutboat/runtime 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @sproutboat/runtime
 
+## 0.9.0
+
+### Minor Changes
+
+- 0b0a666: Add a native standalone R2 direct-upload bridge that streams transfer-ticket
+  request chunks to a temporary blob file, validates the digest, and atomically
+  publishes the object without buffering the upload in the Porffor request body.
+
+## 0.8.0
+
+### Minor Changes
+
+- 493e4e3: Add short-lived R2 direct-transfer tickets for broker-backed sprouts. A
+  loopback HTTP listener streams PUT bodies to file-backed R2 storage, and serves
+  GET and HEAD requests with single-range support without placing object bytes
+  in a binding frame.
+  
+  Tickets are random bearer capabilities with a byte limit, expiry, one-use
+  claim, and optional SHA-256 verification. Native standalone direct transfers
+  remain unavailable until the native HTTP ingress can stream request bodies.
+  
+  For broker deployments, ticket issuance now reserves account-level capacity
+  across every R2 resource. Reservations survive redeploys, expired and orphaned
+  temporary uploads are reclaimed, and the broker retains a configurable free
+  disk floor with capacity and rejected-transfer counters for the dashboard.
+- 5acb93c: Add Cloudflare-shaped resumable R2 multipart uploads. Parts are persisted
+  independently, and standalone completion assembles the final object through a
+  fixed 64 KiB native buffer to keep memory bounded by part size rather than total
+  object size.
+  
+  Unfinished multipart uploads expire after seven days and their persisted part
+  files are removed automatically.
+  
+  Store completed objects as immutable blob generations so a failed overwrite
+  cannot expose new bytes under the previous metadata.
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -31,3 +31,44 @@ The prelude shims the Web API surface handlers expect (URL, Response,
 crypto random values, binding shims, trigger dispatch) and is identical
 for both transports, which is what lets one conformance suite hold them
 honest.
+
+## R2 multipart uploads
+
+R2 bindings implement the Cloudflare multipart method shape for objects that
+are larger than one safe request body:
+
+```js
+const upload = env.FILES.createMultipartUpload("archive.tar", {
+  httpMetadata: { contentType: "application/x-tar" },
+  customMetadata: { source: "backup" },
+});
+
+const parts = [];
+parts.push(await upload.uploadPart(1, firstChunk));
+
+const resumed = env.FILES.resumeMultipartUpload(upload.key, upload.uploadId);
+parts.push(await resumed.uploadPart(2, finalChunk));
+
+const object = await resumed.complete(parts);
+```
+
+Part numbers must be between 1 and 10,000. Parts must be supplied to
+`complete()` in ascending order. Every part except the last must have the same
+size, and the last cannot be larger. Sproutboat permits parts smaller than
+Cloudflare R2's 5 MiB minimum so the default 1 MiB request-body limit remains
+useful. Keep each part below the configured request-body limit.
+
+Each part is persisted independently. Standalone completion copies parts into
+the finished object through a fixed 64 KiB native buffer, so final object size
+does not determine peak Porffor heap use. A single `put()` still buffers its
+whole value; use multipart for larger objects. Call `abort()` to remove an
+unfinished upload and its parts.
+
+Completed objects use immutable, etag-addressed blob generations. The metadata
+row switches to a fully written generation before the previous file is
+removed. If a metadata update fails, readers continue seeing the previous
+generation with its matching size and etag.
+
+Unfinished uploads expire after seven days. The broker removes expired parts
+when another multipart upload starts; a standalone binary removes them when it
+initializes its embedded store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/runtime",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "repository": {

package/src/native-fetch-prelude.js

@@ -1136,6 +1136,26 @@ function __sbR2Object(meta, body) {
   return obj;
 }
 
+function __sbR2Multipart(bucket, key, uploadId) {
+  return {
+    key,
+    uploadId,
+    uploadPart(partNumber, value) {
+      const number = Number(partNumber);
+      if (!Number.isInteger(number) || number < 1 || number > 10000)
+        throw new TypeError("partNumber must be an integer between 1 and 10000");
+      return __sbR2MultipartPut(bucket, key, uploadId, number, value == null ? "" : String(value)).part;
+    },
+    complete(parts) {
+      const r = __sbRpc("r2.multipart.complete", { bucket, key, uploadId, parts: parts || [] });
+      return __sbR2Object(r.object, null);
+    },
+    abort() {
+      __sbRpc("r2.multipart.abort", { bucket, key, uploadId });
+    },
+  };
+}
+
 // Installed only when the project declares bindings. `env` is the module-scoped
 // object from compile.ts (a `const`, but mutable); we add the binding accessors
 // to it in place. compile.ts emits `__sbInstallBindings(env, {...})` right after
@@ -1197,6 +1217,44 @@ globalThis.__sbInstallBindings = function (target, bindings) {
           o.customMetadata || {},
         ).object;
       },
+      createMultipartUpload(key, options) {
+        const objectKey = String(key);
+        const o = options || {};
+        const r = __sbRpc("r2.multipart.create", {
+          bucket: name,
+          key: objectKey,
+          httpMetadata: o.httpMetadata || {},
+          customMetadata: o.customMetadata || {},
+        });
+        return __sbR2Multipart(name, objectKey, r.uploadId);
+      },
+      resumeMultipartUpload(key, uploadId) {
+        return __sbR2Multipart(name, String(key), String(uploadId));
+      },
+      createUploadUrl(key, options) {
+        const o = options || {};
+        const r = __sbRpc("r2.transfer.create", {
+          bucket: name,
+          key: String(key),
+          method: "upload",
+          maxBytes: o.maxBytes,
+          expiresIn: o.expiresIn,
+          sha256: o.sha256,
+          httpMetadata: o.httpMetadata || {},
+          customMetadata: o.customMetadata || {},
+        });
+        return { url: r.url, expiresAt: r.expiresAt };
+      },
+      createDownloadUrl(key, options) {
+        const o = options || {};
+        const r = __sbRpc("r2.transfer.create", {
+          bucket: name,
+          key: String(key),
+          method: "download",
+          expiresIn: o.expiresIn,
+        });
+        return { url: r.url, expiresAt: r.expiresAt };
+      },
       get(key) {
         // #56 — bytes come back out of band on a transport that supports it, so
         // an object body is never JSON-escaped into a frame.

package/src/r2-object.test.js

@@ -24,9 +24,21 @@ if (r2Start === -1 || r2End === -1 || r2End < r2Start) throw new Error("__sbR2Ob
 
 // oxlint-disable-next-line no-function-constructor -- lifting pure blocks out of the text-only prelude for test
 const load = new Function(
-  `${src.slice(utf8Start, utf8End)}\n${src.slice(rawStart, rawEnd)}\n${src.slice(r2Start, r2End)}\nreturn { __sbR2Object };`,
+  "__sbRpc",
+  "__sbR2MultipartPut",
+  `${src.slice(utf8Start, utf8End)}\n${src.slice(rawStart, rawEnd)}\n${src.slice(r2Start, r2End)}\nreturn { __sbR2Object, __sbR2Multipart };`,
 );
-const { __sbR2Object } = load();
+const calls = [];
+const rpc = (op, value) => {
+  calls.push({ op, value });
+  if (op === "r2.multipart.complete") return { object: meta };
+  return { ok: true };
+};
+const putPart = (bucket, key, uploadId, partNumber, body) => {
+  calls.push({ op: "r2.multipart.put", value: { bucket, key, uploadId, partNumber, body } });
+  return { part: { partNumber, etag: `part-${partNumber}` } };
+};
+const { __sbR2Object, __sbR2Multipart } = load(rpc, putPart);
 
 const meta = { key: "f.bin", size: 3, etag: "abc123", uploaded: "2026-09-14T00:00:00.000Z" };
 
@@ -63,3 +75,17 @@ test("toResponse() on an empty body still returns bytes, not the string \"\"", a
   const buf = new Uint8Array(await resp.arrayBuffer());
   expect(buf.length).toBe(0);
 });
+
+test("multipart uploads expose the Cloudflare-shaped uploadPart, complete, and abort methods", () => {
+  calls.length = 0;
+  const upload = __sbR2Multipart("FILES", "archive.bin", "upload-1");
+  expect(upload).toMatchObject({ key: "archive.bin", uploadId: "upload-1" });
+  expect(upload.uploadPart(1, "first")).toEqual({ partNumber: 1, etag: "part-1" });
+  expect(upload.complete([{ partNumber: 1, etag: "part-1" }])).toMatchObject(meta);
+  upload.abort();
+  expect(calls.map((call) => call.op)).toEqual([
+    "r2.multipart.put",
+    "r2.multipart.complete",
+    "r2.multipart.abort",
+  ]);
+});

package/src/transport-broker.js

@@ -303,6 +303,27 @@ globalThis.__sbR2Get = function (bucket, key) {
   return { found: true, object: reply.object, body: __sbTakeBin() };
 };
 
+globalThis.__sbR2MultipartPut = function (bucket, key, uploadId, partNumber, body) {
+  const token = __sbEnv("SB_BROKER_TOKEN");
+  const reply = JSON.parse(
+    __sbCallBin(
+      JSON.stringify({
+        v: 1,
+        id: ++__sbReqId,
+        token,
+        op: "r2.multipart.put",
+        bucket,
+        key,
+        uploadId,
+        partNumber,
+      }),
+      body == null ? "" : String(body),
+    ),
+  );
+  if (reply.ok === false) throw new Error("sproutboat r2.multipart.put: " + (reply.error || "failed"));
+  return reply;
+};
+
 /** Static asset metadata stays JSON; the response body uses the v1 byte tail. */
 globalThis.__sbAssetsGet = function (path) {
   const token = __sbEnv("SB_BROKER_TOKEN");