@tuist/struo 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -2
- package/lib/index.d.ts +56 -0
- package/lib/index.js +339 -0
- package/package.json +24 -4
package/README.md
CHANGED
|
@@ -1,3 +1,26 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Struo JavaScript Software Development Kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@tuist/struo` exposes Struo primitives to Node.js. It loads the same
|
|
4
|
+
native Struo library used by the other language libraries and does not expose script
|
|
5
|
+
execution.
|
|
6
|
+
|
|
7
|
+
```js
|
|
8
|
+
const { Cache } = require("@tuist/struo");
|
|
9
|
+
|
|
10
|
+
async function example() {
|
|
11
|
+
const cache = new Cache();
|
|
12
|
+
const digest = await cache.putBlob(Buffer.from("hello"));
|
|
13
|
+
const bytes = await cache.getBlob(digest);
|
|
14
|
+
|
|
15
|
+
console.assert(bytes.equals(Buffer.from("hello")));
|
|
16
|
+
}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The package looks for a bundled native library under `prebuilds/`. Set
|
|
20
|
+
`STRUO_LIBRARY_PATH` to load a custom `libstruo` build.
|
|
21
|
+
|
|
22
|
+
Use `new Cache({ workspaceRoot })` to share the effective provider configured
|
|
23
|
+
for a repository, or `new Cache({ localCacheRoot })` for isolation. Use
|
|
24
|
+
`putFile` and `getBlobToFile` for large payloads so the host does not need to
|
|
25
|
+
hold their complete contents in JavaScript memory. `ActionKey` builds a stable
|
|
26
|
+
digest from ordered, labeled inputs.
|
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
export interface ActionResult {
|
|
2
|
+
exitCode: number;
|
|
3
|
+
stdout?: string | null;
|
|
4
|
+
stderr?: string | null;
|
|
5
|
+
outputs?: Record<string, string>;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export interface CacheStats {
|
|
9
|
+
blobCount: number;
|
|
10
|
+
blobBytes: number;
|
|
11
|
+
actionCount: number;
|
|
12
|
+
actionBytes: number;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export class StruoError extends Error {}
|
|
16
|
+
|
|
17
|
+
export interface CacheOptions {
|
|
18
|
+
localCacheRoot?: string;
|
|
19
|
+
workspaceRoot?: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export class Cache {
|
|
23
|
+
constructor(options?: CacheOptions);
|
|
24
|
+
version(): string;
|
|
25
|
+
/**
|
|
26
|
+
* Strings use Unicode Transformation Format, 8-bit before hashing.
|
|
27
|
+
*/
|
|
28
|
+
digest(bytes: Buffer | Uint8Array | string): string;
|
|
29
|
+
/**
|
|
30
|
+
* Strings use Unicode Transformation Format, 8-bit before being stored.
|
|
31
|
+
*
|
|
32
|
+
* Use putFile for large blobs to avoid loading the complete payload into
|
|
33
|
+
* JavaScript memory.
|
|
34
|
+
*/
|
|
35
|
+
putBlob(bytes: Buffer | Uint8Array | string): Promise<string>;
|
|
36
|
+
putFile(path: string): Promise<string>;
|
|
37
|
+
getBlob(digest: string): Promise<Buffer>;
|
|
38
|
+
getBlobToFile(digest: string, path: string): Promise<number>;
|
|
39
|
+
hasBlob(digest: string): Promise<boolean>;
|
|
40
|
+
putActionResult(result: ActionResult, actionDigest: string): Promise<boolean>;
|
|
41
|
+
getActionResult(actionDigest: string): Promise<ActionResult | null>;
|
|
42
|
+
forgetAction(actionDigest: string): Promise<boolean>;
|
|
43
|
+
stats(): Promise<CacheStats>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export class ActionKey {
|
|
47
|
+
constructor(namespace: string);
|
|
48
|
+
addBytes(label: string, bytes: Buffer | Uint8Array | string): this;
|
|
49
|
+
addDigest(label: string, digest: string): this;
|
|
50
|
+
digest(): string;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Strings use Unicode Transformation Format, 8-bit before hashing.
|
|
55
|
+
*/
|
|
56
|
+
export function digest(bytes: Buffer | Uint8Array | string): string;
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("node:fs");
|
|
4
|
+
const path = require("node:path");
|
|
5
|
+
const koffi = require("koffi");
|
|
6
|
+
|
|
7
|
+
class StruoError extends Error {
|
|
8
|
+
constructor(message) {
|
|
9
|
+
super(message);
|
|
10
|
+
this.name = "StruoError";
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
const native = loadNative();
|
|
15
|
+
const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
|
|
16
|
+
|
|
17
|
+
class Cache {
|
|
18
|
+
constructor(options = {}) {
|
|
19
|
+
if (options == null || typeof options !== "object" || Array.isArray(options)) {
|
|
20
|
+
throw new TypeError("Cache options must be an object");
|
|
21
|
+
}
|
|
22
|
+
const { localCacheRoot, workspaceRoot } = options;
|
|
23
|
+
if (localCacheRoot != null && workspaceRoot != null) {
|
|
24
|
+
throw new TypeError("localCacheRoot and workspaceRoot cannot be used together");
|
|
25
|
+
}
|
|
26
|
+
if (localCacheRoot != null && typeof localCacheRoot !== "string") {
|
|
27
|
+
throw new TypeError("localCacheRoot must be a string");
|
|
28
|
+
}
|
|
29
|
+
if (workspaceRoot != null && typeof workspaceRoot !== "string") {
|
|
30
|
+
throw new TypeError("workspaceRoot must be a string");
|
|
31
|
+
}
|
|
32
|
+
this.selection = {
|
|
33
|
+
...(localCacheRoot == null ? {} : { local_cache_root: localCacheRoot }),
|
|
34
|
+
...(workspaceRoot == null ? {} : { workspace_root: workspaceRoot }),
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
version() {
|
|
39
|
+
return native.struo_version() || "";
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
digest(bytes) {
|
|
43
|
+
const buffer = toBuffer(bytes, "Cache#digest bytes");
|
|
44
|
+
return decodeStringResponse(native.struo_digest_bytes(buffer, buffer.length));
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
async putBlob(bytes) {
|
|
48
|
+
const buffer = toBuffer(bytes, "Cache#putBlob bytes");
|
|
49
|
+
return decodeRequest(
|
|
50
|
+
native.struo_cache_put_blob_json,
|
|
51
|
+
{ ...this.selection, bytes: Array.from(buffer) },
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
async putFile(filePath) {
|
|
56
|
+
validatePath(filePath, "filePath");
|
|
57
|
+
return decodeRequest(native.struo_cache_put_file_json, {
|
|
58
|
+
...this.selection,
|
|
59
|
+
path: filePath,
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
async getBlob(digest) {
|
|
64
|
+
validateDigest(digest, "digest");
|
|
65
|
+
const response = decodeRequest(native.struo_cache_get_blob_json, {
|
|
66
|
+
...this.selection,
|
|
67
|
+
digest,
|
|
68
|
+
});
|
|
69
|
+
return Buffer.from(response.bytes);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
async getBlobToFile(digest, filePath) {
|
|
73
|
+
validateDigest(digest, "digest");
|
|
74
|
+
validatePath(filePath, "filePath");
|
|
75
|
+
return decodeRequest(native.struo_cache_get_blob_to_file_json, {
|
|
76
|
+
...this.selection,
|
|
77
|
+
digest,
|
|
78
|
+
path: filePath,
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
async hasBlob(digest) {
|
|
83
|
+
validateDigest(digest, "digest");
|
|
84
|
+
return decodeRequest(native.struo_cache_has_blob_json, {
|
|
85
|
+
...this.selection,
|
|
86
|
+
digest,
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
async putActionResult(result, actionDigest) {
|
|
91
|
+
validateDigest(actionDigest, "actionDigest");
|
|
92
|
+
return decodeRequest(
|
|
93
|
+
native.struo_cache_put_action_result_json,
|
|
94
|
+
{
|
|
95
|
+
...this.selection,
|
|
96
|
+
action_digest: actionDigest,
|
|
97
|
+
result: actionResultToNative(result),
|
|
98
|
+
},
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
async getActionResult(actionDigest) {
|
|
103
|
+
validateDigest(actionDigest, "actionDigest");
|
|
104
|
+
const result = decodeRequest(
|
|
105
|
+
native.struo_cache_get_action_result_json,
|
|
106
|
+
{ ...this.selection, action_digest: actionDigest },
|
|
107
|
+
);
|
|
108
|
+
return result === null ? null : actionResultFromNative(result);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
async forgetAction(actionDigest) {
|
|
112
|
+
validateDigest(actionDigest, "actionDigest");
|
|
113
|
+
return decodeRequest(
|
|
114
|
+
native.struo_cache_forget_action_json,
|
|
115
|
+
{ ...this.selection, action_digest: actionDigest },
|
|
116
|
+
);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async stats() {
|
|
120
|
+
const stats = decodeRequest(native.struo_cache_stats_json, this.selection);
|
|
121
|
+
return {
|
|
122
|
+
blobCount: stats.blob_count,
|
|
123
|
+
blobBytes: stats.blob_bytes,
|
|
124
|
+
actionCount: stats.action_count,
|
|
125
|
+
actionBytes: stats.action_bytes,
|
|
126
|
+
};
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
class ActionKey {
|
|
131
|
+
constructor(namespace) {
|
|
132
|
+
if (typeof namespace !== "string") {
|
|
133
|
+
throw new TypeError("ActionKey namespace must be a string");
|
|
134
|
+
}
|
|
135
|
+
this.namespace = namespace;
|
|
136
|
+
this.inputs = [];
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
addBytes(label, bytes) {
|
|
140
|
+
validateLabel(label);
|
|
141
|
+
const buffer = toBuffer(bytes, "ActionKey#addBytes bytes");
|
|
142
|
+
this.inputs.push({ kind: "bytes", label, bytes: Array.from(buffer) });
|
|
143
|
+
return this;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
addDigest(label, digest) {
|
|
147
|
+
validateLabel(label);
|
|
148
|
+
validateDigest(digest, "digest");
|
|
149
|
+
this.inputs.push({ kind: "digest", label, digest });
|
|
150
|
+
return this;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
digest() {
|
|
154
|
+
return decodeRequest(native.struo_action_key_json, {
|
|
155
|
+
namespace: this.namespace,
|
|
156
|
+
inputs: this.inputs,
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function digest(bytes) {
|
|
162
|
+
return new Cache().digest(bytes);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function decodeStringResponse(pointer) {
|
|
166
|
+
return decodeResponse(pointer);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
function decodeRequest(fn, request) {
|
|
170
|
+
const pointer = fn(JSON.stringify(request));
|
|
171
|
+
return decodeResponse(pointer);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function decodeResponse(pointer) {
|
|
175
|
+
if (pointer == null) {
|
|
176
|
+
throw new StruoError("native Struo function returned null");
|
|
177
|
+
}
|
|
178
|
+
let response;
|
|
179
|
+
try {
|
|
180
|
+
response = JSON.parse(pointer);
|
|
181
|
+
} catch (error) {
|
|
182
|
+
throw new StruoError(
|
|
183
|
+
`native Struo response must be valid JavaScript Object Notation: ${error.message}`,
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
if (response.status === "ok") {
|
|
187
|
+
return response.value;
|
|
188
|
+
}
|
|
189
|
+
throw new StruoError(response.message || "Struo native call failed");
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
function actionResultToNative(result) {
|
|
193
|
+
return {
|
|
194
|
+
exit_code: result.exitCode,
|
|
195
|
+
stdout: result.stdout ?? null,
|
|
196
|
+
stderr: result.stderr ?? null,
|
|
197
|
+
outputs: result.outputs ?? {},
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
function actionResultFromNative(result) {
|
|
202
|
+
return {
|
|
203
|
+
exitCode: result.exit_code,
|
|
204
|
+
stdout: result.stdout ?? null,
|
|
205
|
+
stderr: result.stderr ?? null,
|
|
206
|
+
outputs: result.outputs ?? {},
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function validateDigest(value, name) {
|
|
211
|
+
if (typeof value !== "string" || !DIGEST_PATTERN.test(value)) {
|
|
212
|
+
throw new StruoError(`${name} must be a lowercase BLAKE3 hex digest`);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
function validateLabel(value) {
|
|
217
|
+
if (typeof value !== "string") {
|
|
218
|
+
throw new TypeError("ActionKey input label must be a string");
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function validatePath(value, name) {
|
|
223
|
+
if (typeof value !== "string" || value.length === 0) {
|
|
224
|
+
throw new TypeError(`${name} must be a non-empty string`);
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function toBuffer(bytes, name) {
|
|
229
|
+
if (Buffer.isBuffer(bytes)) {
|
|
230
|
+
return bytes;
|
|
231
|
+
}
|
|
232
|
+
if (bytes instanceof Uint8Array) {
|
|
233
|
+
return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
|
|
234
|
+
}
|
|
235
|
+
if (typeof bytes === "string") {
|
|
236
|
+
return Buffer.from(bytes, "utf8");
|
|
237
|
+
}
|
|
238
|
+
throw new TypeError(`${name} must be a Buffer, Uint8Array, or string`);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function loadNative() {
|
|
242
|
+
const library = koffi.load(resolveLibraryPath());
|
|
243
|
+
const struoStringFree = library.func("void struo_string_free(void *value)");
|
|
244
|
+
const struoString = koffi.disposable("StruoString", "str", struoStringFree);
|
|
245
|
+
|
|
246
|
+
return {
|
|
247
|
+
struo_version: library.func("struo_version", struoString, []),
|
|
248
|
+
struo_digest_bytes: library.func("struo_digest_bytes", struoString, [
|
|
249
|
+
"const void *",
|
|
250
|
+
"size_t",
|
|
251
|
+
]),
|
|
252
|
+
struo_action_key_json: library.func("struo_action_key_json", struoString, [
|
|
253
|
+
"str",
|
|
254
|
+
]),
|
|
255
|
+
struo_cache_put_blob_json: library.func(
|
|
256
|
+
"struo_cache_put_blob_json",
|
|
257
|
+
struoString,
|
|
258
|
+
["str"],
|
|
259
|
+
),
|
|
260
|
+
struo_cache_put_file_json: library.func(
|
|
261
|
+
"struo_cache_put_file_json",
|
|
262
|
+
struoString,
|
|
263
|
+
["str"],
|
|
264
|
+
),
|
|
265
|
+
struo_cache_get_blob_json: library.func(
|
|
266
|
+
"struo_cache_get_blob_json",
|
|
267
|
+
struoString,
|
|
268
|
+
["str"],
|
|
269
|
+
),
|
|
270
|
+
struo_cache_get_blob_to_file_json: library.func(
|
|
271
|
+
"struo_cache_get_blob_to_file_json",
|
|
272
|
+
struoString,
|
|
273
|
+
["str"],
|
|
274
|
+
),
|
|
275
|
+
struo_cache_has_blob_json: library.func(
|
|
276
|
+
"struo_cache_has_blob_json",
|
|
277
|
+
struoString,
|
|
278
|
+
["str"],
|
|
279
|
+
),
|
|
280
|
+
struo_cache_put_action_result_json: library.func(
|
|
281
|
+
"struo_cache_put_action_result_json",
|
|
282
|
+
struoString,
|
|
283
|
+
["str"],
|
|
284
|
+
),
|
|
285
|
+
struo_cache_get_action_result_json: library.func(
|
|
286
|
+
"struo_cache_get_action_result_json",
|
|
287
|
+
struoString,
|
|
288
|
+
["str"],
|
|
289
|
+
),
|
|
290
|
+
struo_cache_forget_action_json: library.func(
|
|
291
|
+
"struo_cache_forget_action_json",
|
|
292
|
+
struoString,
|
|
293
|
+
["str"],
|
|
294
|
+
),
|
|
295
|
+
struo_cache_stats_json: library.func("struo_cache_stats_json", struoString, [
|
|
296
|
+
"str",
|
|
297
|
+
]),
|
|
298
|
+
};
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
function resolveLibraryPath() {
|
|
302
|
+
if (process.env.STRUO_LIBRARY_PATH) {
|
|
303
|
+
return process.env.STRUO_LIBRARY_PATH;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const candidate = path.join(
|
|
307
|
+
__dirname,
|
|
308
|
+
"..",
|
|
309
|
+
"prebuilds",
|
|
310
|
+
`${process.platform}-${process.arch}`,
|
|
311
|
+
libraryName(),
|
|
312
|
+
);
|
|
313
|
+
if (fs.existsSync(candidate)) {
|
|
314
|
+
return candidate;
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
throw new StruoError(
|
|
318
|
+
`missing native Struo library for ${process.platform}-${process.arch}; ` +
|
|
319
|
+
"set STRUO_LIBRARY_PATH or install a package that includes this platform",
|
|
320
|
+
);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
function libraryName() {
|
|
324
|
+
switch (process.platform) {
|
|
325
|
+
case "darwin":
|
|
326
|
+
return "libstruo.dylib";
|
|
327
|
+
case "win32":
|
|
328
|
+
return "struo.dll";
|
|
329
|
+
default:
|
|
330
|
+
return "libstruo.so";
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
module.exports = {
|
|
335
|
+
ActionKey,
|
|
336
|
+
Cache,
|
|
337
|
+
StruoError,
|
|
338
|
+
digest,
|
|
339
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,26 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tuist/struo",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "JavaScript software development kit for Struo cache access",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/tuist/struo.git",
|
|
9
|
+
"directory": "packages/js"
|
|
10
|
+
},
|
|
11
|
+
"main": "lib/index.js",
|
|
12
|
+
"types": "lib/index.d.ts",
|
|
13
|
+
"files": [
|
|
14
|
+
"lib",
|
|
15
|
+
"prebuilds"
|
|
16
|
+
],
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=18"
|
|
19
|
+
},
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"koffi": "^3.0.0"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"test": "node test.js"
|
|
25
|
+
}
|
|
26
|
+
}
|