buildonce 0.1.0 → 0.15.0

package/README.md

@@ -18,3 +18,7 @@ async function example() {
 
 The package looks for a bundled native library under `prebuilds/`. Set
 `ONCE_LIBRARY_PATH` to load a custom `libonce` build.
+
+`putBlob` sends bytes to the native library through the JSON SDK ABI. This
+keeps the package portable across platforms, but it means very large blobs are
+materialized as JSON byte arrays before crossing into Rust.

package/lib/index.d.ts

@@ -16,7 +16,17 @@ export class OnceError extends Error {}
 
 export class Cache {
   version(): string;
+  /**
+   * Strings are encoded as UTF-8 before hashing.
+   */
   digest(bytes: Buffer | Uint8Array | string): string;
+  /**
+   * Strings are encoded as UTF-8 before being stored.
+   *
+   * Blob bytes currently cross the native boundary as JSON arrays, so very
+   * large blobs should use the Rust SDK or CLI until the JavaScript SDK has a
+   * streaming native ABI.
+   */
   putBlob(bytes: Buffer | Uint8Array | string): Promise<string>;
   getBlob(digest: string): Promise<Buffer>;
   hasBlob(digest: string): Promise<boolean>;
@@ -26,4 +36,7 @@ export class Cache {
   stats(): Promise<CacheStats>;
 }
 
+/**
+ * Strings are encoded as UTF-8 before hashing.
+ */
 export function digest(bytes: Buffer | Uint8Array | string): string;

package/lib/index.js

@@ -12,6 +12,7 @@ class OnceError extends Error {
 }
 
 const native = loadNative();
+const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 
 class Cache {
   version() {
@@ -19,13 +20,12 @@ class Cache {
   }
 
   digest(bytes) {
-    const buffer = toBuffer(bytes);
-    const pointer = buffer.length === 0 ? null : buffer;
-    return decodeStringResponse(native.once_digest_bytes(pointer, buffer.length));
+    const buffer = toBuffer(bytes, "Cache#digest bytes");
+    return decodeStringResponse(native.once_digest_bytes(buffer, buffer.length));
   }
 
   async putBlob(bytes) {
-    const buffer = toBuffer(bytes);
+    const buffer = toBuffer(bytes, "Cache#putBlob bytes");
     return decodeRequest(
       native.once_cache_put_blob_json,
       { bytes: Array.from(buffer) },
@@ -33,15 +33,18 @@ class Cache {
   }
 
   async getBlob(digest) {
+    validateDigest(digest, "digest");
     const response = decodeRequest(native.once_cache_get_blob_json, { digest });
     return Buffer.from(response.bytes);
   }
 
   async hasBlob(digest) {
+    validateDigest(digest, "digest");
     return decodeRequest(native.once_cache_has_blob_json, { digest });
   }
 
   async putActionResult(result, actionDigest) {
+    validateDigest(actionDigest, "actionDigest");
     return decodeRequest(
       native.once_cache_put_action_result_json,
       {
@@ -52,6 +55,7 @@ class Cache {
   }
 
   async getActionResult(actionDigest) {
+    validateDigest(actionDigest, "actionDigest");
     const result = decodeRequest(
       native.once_cache_get_action_result_json,
       { action_digest: actionDigest },
@@ -60,6 +64,7 @@ class Cache {
   }
 
   async forgetAction(actionDigest) {
+    validateDigest(actionDigest, "actionDigest");
     return decodeRequest(
       native.once_cache_forget_action_json,
       { action_digest: actionDigest },
@@ -94,7 +99,12 @@ function decodeResponse(pointer) {
   if (pointer == null) {
     throw new OnceError("native Once function returned null");
   }
-  const response = JSON.parse(pointer);
+  let response;
+  try {
+    response = JSON.parse(pointer);
+  } catch (error) {
+    throw new OnceError(`native Once response must be valid JSON: ${error.message}`);
+  }
   if (response.status === "ok") {
     return response.value;
   }
@@ -119,7 +129,13 @@ function actionResultFromNative(result) {
   };
 }
 
-function toBuffer(bytes) {
+function validateDigest(value, name) {
+  if (typeof value !== "string" || !DIGEST_PATTERN.test(value)) {
+    throw new OnceError(`${name} must be a lowercase BLAKE3 hex digest`);
+  }
+}
+
+function toBuffer(bytes, name) {
   if (Buffer.isBuffer(bytes)) {
     return bytes;
   }
@@ -127,9 +143,9 @@ function toBuffer(bytes) {
     return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   }
   if (typeof bytes === "string") {
-    return Buffer.from(bytes);
+    return Buffer.from(bytes, "utf8");
   }
-  throw new TypeError("bytes must be a Buffer, Uint8Array, or string");
+  throw new TypeError(`${name} must be a Buffer, Uint8Array, or string`);
 }
 
 function loadNative() {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "buildonce",
-  "version": "0.1.0",
+  "version": "0.15.0",
   "description": "JavaScript SDK for Once cache access",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tuist/once.git",
+    "url": "git+https://github.com/tuist/once.git",
     "directory": "packages/js"
   },
   "main": "lib/index.js",