buildonce 0.32.0 → 0.33.0

package/README.md

@@ -1,7 +1,7 @@
-# Once JavaScript SDK
+# Once JavaScript Software Development Kit
 
 `buildonce` exposes Once primitives to Node.js. It loads the same
-native Once library used by the other SDKs and does not expose script
+native Once library used by the other language libraries and does not expose script
 execution.
 
 ```js
@@ -19,6 +19,8 @@ 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.
+Use `new Cache({ workspaceRoot })` to share the effective provider configured
+for a repository, or `new Cache({ localCacheRoot })` for isolation. Use
+`putFile` and `getBlobToFile` for large payloads so the host does not need to
+hold their complete contents in JavaScript memory. `ActionKey` builds a stable
+digest from ordered, labeled inputs.

package/lib/index.d.ts

@@ -14,21 +14,28 @@ export interface CacheStats {
 
 export class OnceError extends Error {}
 
+export interface CacheOptions {
+  localCacheRoot?: string;
+  workspaceRoot?: string;
+}
+
 export class Cache {
+  constructor(options?: CacheOptions);
   version(): string;
   /**
-   * Strings are encoded as UTF-8 before hashing.
+   * Strings use Unicode Transformation Format, 8-bit before hashing.
    */
   digest(bytes: Buffer | Uint8Array | string): string;
   /**
-   * Strings are encoded as UTF-8 before being stored.
+   * Strings use Unicode Transformation Format, 8-bit 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.
+   * Use putFile for large blobs to avoid loading the complete payload into
+   * JavaScript memory.
    */
   putBlob(bytes: Buffer | Uint8Array | string): Promise<string>;
+  putFile(path: string): Promise<string>;
   getBlob(digest: string): Promise<Buffer>;
+  getBlobToFile(digest: string, path: string): Promise<number>;
   hasBlob(digest: string): Promise<boolean>;
   putActionResult(result: ActionResult, actionDigest: string): Promise<boolean>;
   getActionResult(actionDigest: string): Promise<ActionResult | null>;
@@ -36,7 +43,14 @@ export class Cache {
   stats(): Promise<CacheStats>;
 }
 
+export class ActionKey {
+  constructor(namespace: string);
+  addBytes(label: string, bytes: Buffer | Uint8Array | string): this;
+  addDigest(label: string, digest: string): this;
+  digest(): string;
+}
+
 /**
- * Strings are encoded as UTF-8 before hashing.
+ * Strings use Unicode Transformation Format, 8-bit before hashing.
  */
 export function digest(bytes: Buffer | Uint8Array | string): string;

package/lib/index.js

@@ -15,6 +15,26 @@ const native = loadNative();
 const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 
 class Cache {
+  constructor(options = {}) {
+    if (options == null || typeof options !== "object" || Array.isArray(options)) {
+      throw new TypeError("Cache options must be an object");
+    }
+    const { localCacheRoot, workspaceRoot } = options;
+    if (localCacheRoot != null && workspaceRoot != null) {
+      throw new TypeError("localCacheRoot and workspaceRoot cannot be used together");
+    }
+    if (localCacheRoot != null && typeof localCacheRoot !== "string") {
+      throw new TypeError("localCacheRoot must be a string");
+    }
+    if (workspaceRoot != null && typeof workspaceRoot !== "string") {
+      throw new TypeError("workspaceRoot must be a string");
+    }
+    this.selection = {
+      ...(localCacheRoot == null ? {} : { local_cache_root: localCacheRoot }),
+      ...(workspaceRoot == null ? {} : { workspace_root: workspaceRoot }),
+    };
+  }
+
   version() {
     return native.once_version() || "";
   }
@@ -28,19 +48,43 @@ class Cache {
     const buffer = toBuffer(bytes, "Cache#putBlob bytes");
     return decodeRequest(
       native.once_cache_put_blob_json,
-      { bytes: Array.from(buffer) },
+      { ...this.selection, bytes: Array.from(buffer) },
     );
   }
 
+  async putFile(filePath) {
+    validatePath(filePath, "filePath");
+    return decodeRequest(native.once_cache_put_file_json, {
+      ...this.selection,
+      path: filePath,
+    });
+  }
+
   async getBlob(digest) {
     validateDigest(digest, "digest");
-    const response = decodeRequest(native.once_cache_get_blob_json, { digest });
+    const response = decodeRequest(native.once_cache_get_blob_json, {
+      ...this.selection,
+      digest,
+    });
     return Buffer.from(response.bytes);
   }
 
+  async getBlobToFile(digest, filePath) {
+    validateDigest(digest, "digest");
+    validatePath(filePath, "filePath");
+    return decodeRequest(native.once_cache_get_blob_to_file_json, {
+      ...this.selection,
+      digest,
+      path: filePath,
+    });
+  }
+
   async hasBlob(digest) {
     validateDigest(digest, "digest");
-    return decodeRequest(native.once_cache_has_blob_json, { digest });
+    return decodeRequest(native.once_cache_has_blob_json, {
+      ...this.selection,
+      digest,
+    });
   }
 
   async putActionResult(result, actionDigest) {
@@ -48,6 +92,7 @@ class Cache {
     return decodeRequest(
       native.once_cache_put_action_result_json,
       {
+        ...this.selection,
         action_digest: actionDigest,
         result: actionResultToNative(result),
       },
@@ -58,7 +103,7 @@ class Cache {
     validateDigest(actionDigest, "actionDigest");
     const result = decodeRequest(
       native.once_cache_get_action_result_json,
-      { action_digest: actionDigest },
+      { ...this.selection, action_digest: actionDigest },
     );
     return result === null ? null : actionResultFromNative(result);
   }
@@ -67,12 +112,12 @@ class Cache {
     validateDigest(actionDigest, "actionDigest");
     return decodeRequest(
       native.once_cache_forget_action_json,
-      { action_digest: actionDigest },
+      { ...this.selection, action_digest: actionDigest },
     );
   }
 
   async stats() {
-    const stats = decodeRequest(native.once_cache_stats_json, {});
+    const stats = decodeRequest(native.once_cache_stats_json, this.selection);
     return {
       blobCount: stats.blob_count,
       blobBytes: stats.blob_bytes,
@@ -82,6 +127,37 @@ class Cache {
   }
 }
 
+class ActionKey {
+  constructor(namespace) {
+    if (typeof namespace !== "string") {
+      throw new TypeError("ActionKey namespace must be a string");
+    }
+    this.namespace = namespace;
+    this.inputs = [];
+  }
+
+  addBytes(label, bytes) {
+    validateLabel(label);
+    const buffer = toBuffer(bytes, "ActionKey#addBytes bytes");
+    this.inputs.push({ kind: "bytes", label, bytes: Array.from(buffer) });
+    return this;
+  }
+
+  addDigest(label, digest) {
+    validateLabel(label);
+    validateDigest(digest, "digest");
+    this.inputs.push({ kind: "digest", label, digest });
+    return this;
+  }
+
+  digest() {
+    return decodeRequest(native.once_action_key_json, {
+      namespace: this.namespace,
+      inputs: this.inputs,
+    });
+  }
+}
+
 function digest(bytes) {
   return new Cache().digest(bytes);
 }
@@ -103,7 +179,9 @@ function decodeResponse(pointer) {
   try {
     response = JSON.parse(pointer);
   } catch (error) {
-    throw new OnceError(`native Once response must be valid JSON: ${error.message}`);
+    throw new OnceError(
+      `native Once response must be valid JavaScript Object Notation: ${error.message}`,
+    );
   }
   if (response.status === "ok") {
     return response.value;
@@ -135,6 +213,18 @@ function validateDigest(value, name) {
   }
 }
 
+function validateLabel(value) {
+  if (typeof value !== "string") {
+    throw new TypeError("ActionKey input label must be a string");
+  }
+}
+
+function validatePath(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+
 function toBuffer(bytes, name) {
   if (Buffer.isBuffer(bytes)) {
     return bytes;
@@ -159,16 +249,29 @@ function loadNative() {
       "const void *",
       "size_t",
     ]),
+    once_action_key_json: library.func("once_action_key_json", onceString, [
+      "str",
+    ]),
     once_cache_put_blob_json: library.func(
       "once_cache_put_blob_json",
       onceString,
       ["str"],
     ),
+    once_cache_put_file_json: library.func(
+      "once_cache_put_file_json",
+      onceString,
+      ["str"],
+    ),
     once_cache_get_blob_json: library.func(
       "once_cache_get_blob_json",
       onceString,
       ["str"],
     ),
+    once_cache_get_blob_to_file_json: library.func(
+      "once_cache_get_blob_to_file_json",
+      onceString,
+      ["str"],
+    ),
     once_cache_has_blob_json: library.func(
       "once_cache_has_blob_json",
       onceString,
@@ -229,6 +332,7 @@ function libraryName() {
 }
 
 module.exports = {
+  ActionKey,
   Cache,
   OnceError,
   digest,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "buildonce",
-  "version": "0.32.0",
-  "description": "JavaScript SDK for Once cache access",
+  "version": "0.33.0",
+  "description": "JavaScript software development kit for Once cache access",
   "license": "MIT",
   "repository": {
     "type": "git",