@idyl-sh/sdk 0.1.0 → 0.1.1

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 CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  # IDYL TypeScript SDK
4
4
 
5
+ [![npm](https://img.shields.io/npm/v/@idyl-sh/sdk.svg)](https://www.npmjs.com/package/@idyl-sh/sdk)
5
6
  [![CI](https://github.com/idyl-labs/sdk-typescript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/idyl-labs/sdk-typescript/actions/workflows/ci.yml)
6
7
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
7
8
  [![Node.js](https://img.shields.io/badge/node-%3E%3D22.3-brightgreen.svg)](https://nodejs.org)
@@ -136,11 +137,31 @@ const terminal = await computer.terminal({ size: { cols: 120, rows: 40 } });
136
137
  [`examples/browser-terminal.ts`](examples/browser-terminal.ts) connects a
137
138
  terminal to xterm.js.
138
139
 
140
+ ### Lists
141
+
142
+ Every list answers in pages. `idyl.computers.list()` walks them for you,
143
+ newest Computer first; `listPage` reads one, and its `continue` asks for the
144
+ next. The first page counts what the list holds up to 1,000:
145
+
146
+ ```ts
147
+ const first = await idyl.computers.listPage({ limit: 100 });
148
+ console.log(first.totalCountIsLowerBound ? "1,000+" : first.totalCount);
149
+ if (first.continue !== undefined) {
150
+ const second = await idyl.computers.listPage({ continue: first.continue });
151
+ console.log(second.items.length);
152
+ }
153
+ ```
154
+
155
+ `computer.files.list(path, { limit })` and `computer.files.listPage(path)`
156
+ page a directory the same way.
157
+
139
158
  ### More
140
159
 
141
160
  Every export is documented in its type declarations. The client also covers
142
161
  Secrets (`idyl.secrets`), the record of every time a Secret's value was
143
162
  opened (`idyl.secrets.decryptions(name)` and `computer.decryptions()`),
163
+ how much a Secret is used (`idyl.secrets.usage(name)` and
164
+ `idyl.computers.secretUsage(id)`, counted up to 1,000),
144
165
  history (`computer.history()`), wake and sleep (`computer.wake()`, `computer.sleep()`) and billing (`idyl.billing`).
145
166
 
146
167
  ## Authentication
@@ -175,6 +196,10 @@ try {
175
196
  }
176
197
  ```
177
198
 
199
+ A request made faster than the Account's plan allows, such as listing or
200
+ creating Computers in a tight loop, rejects with `ERROR_CODE_RATE_LIMITED`;
201
+ its `retryAfterMs` is how long to wait before the same request succeeds.
202
+
178
203
  A request that does not complete rejects with a `TransportError`, and a
179
204
  command that exits other than with 0 with an `ExitError`.
180
205
 
@@ -36,6 +36,45 @@ type PageToWorker = {
36
36
  readonly account: string;
37
37
  readonly computer: string;
38
38
  readonly minEpoch: string;
39
+ } | {
40
+ readonly type: "open-service-lane";
41
+ readonly ref: number;
42
+ readonly dock: number;
43
+ readonly principal: string;
44
+ } | {
45
+ readonly type: "open-service";
46
+ readonly ref: number;
47
+ readonly dock: number;
48
+ readonly lane: number;
49
+ /** The stream profile the lane stream's header names. */
50
+ readonly profile: string;
51
+ /** The trust anchors of the service's certificate, DER. */
52
+ readonly roots: readonly Uint8Array[];
53
+ readonly chain: readonly Uint8Array[];
54
+ /** The exact SPIFFE ID the service's certificate must name. */
55
+ readonly principal: string;
56
+ } | {
57
+ readonly type: "service-write";
58
+ readonly ref: number;
59
+ readonly dock: number;
60
+ readonly service: number;
61
+ readonly bytes: Uint8Array;
62
+ } | {
63
+ readonly type: "close-service";
64
+ readonly ref: number;
65
+ readonly dock: number;
66
+ readonly service: number;
67
+ }
68
+ /**
69
+ * The page has handled the last `service-data` of a service connection:
70
+ * the Worker reads its stream again. Until then it reads none, so the
71
+ * stream's sender is held by its receive window.
72
+ */
73
+ | {
74
+ readonly type: "service-release";
75
+ readonly ref: number;
76
+ readonly dock: number;
77
+ readonly service: number;
39
78
  } | {
40
79
  readonly type: "close-computer";
41
80
  readonly ref: number;
@@ -80,9 +119,15 @@ type WorkerToPage =
80
119
  readonly type: "key";
81
120
  readonly certificateRequest: Uint8Array;
82
121
  readonly publicKey: Uint8Array;
83
- } | {
122
+ }
123
+ /**
124
+ * The dock is admitted; `serviceLaneProfile` is the client service lane
125
+ * profile its edge serves, empty when it serves none.
126
+ */
127
+ | {
84
128
  readonly type: "docked";
85
129
  readonly dock: number;
130
+ readonly serviceLaneProfile: string;
86
131
  } | {
87
132
  readonly type: "drain";
88
133
  readonly dock: number;
@@ -112,6 +157,20 @@ type WorkerToPage =
112
157
  readonly computer: number;
113
158
  readonly reason: string;
114
159
  readonly refusal?: number;
160
+ } | {
161
+ readonly type: "service-established";
162
+ readonly dock: number;
163
+ readonly service: number;
164
+ } | {
165
+ readonly type: "service-ended";
166
+ readonly dock: number;
167
+ readonly service: number;
168
+ readonly reason: string;
169
+ } | {
170
+ readonly type: "service-data";
171
+ readonly dock: number;
172
+ readonly service: number;
173
+ readonly bytes: Uint8Array;
115
174
  } | {
116
175
  readonly type: "data";
117
176
  readonly dock: number;
@@ -25,6 +25,13 @@ var WorkerClient = class {
25
25
  closeComputer(computer) {
26
26
  wasm.workerclient_closeComputer(this.__wbg_ptr, computer);
27
27
  }
28
+ /**
29
+ * Ends a service connection.
30
+ * @param {number} service
31
+ */
32
+ closeService(service) {
33
+ wasm.workerclient_closeService(this.__wbg_ptr, service);
34
+ }
28
35
  /**
29
36
  * Ends the dock gracefully.
30
37
  */
@@ -175,6 +182,61 @@ var WorkerClient = class {
175
182
  wasm.__wbindgen_add_to_stack_pointer(16);
176
183
  }
177
184
  }
185
+ /**
186
+ * Asks for a client service lane to the Zone service named exactly
187
+ * `principal`.
188
+ * @param {string} principal
189
+ * @returns {number}
190
+ */
191
+ openServiceLane(principal) {
192
+ try {
193
+ const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
194
+ const ptr0 = passStringToWasm0(principal, wasm.__wbindgen_export2, wasm.__wbindgen_export3);
195
+ const len0 = WASM_VECTOR_LEN;
196
+ wasm.workerclient_openServiceLane(retptr, this.__wbg_ptr, ptr0, len0);
197
+ var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
198
+ var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
199
+ var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
200
+ if (r2) {
201
+ throw takeObject(r1);
202
+ }
203
+ return r0 >>> 0;
204
+ } finally {
205
+ wasm.__wbindgen_add_to_stack_pointer(16);
206
+ }
207
+ }
208
+ /**
209
+ * Opens the one stream of the client service lane `lane`, whose header
210
+ * names the stream profile `profile`, and starts TLS with the service,
211
+ * which must prove exactly `principal` against `roots`.
212
+ * @param {number} lane
213
+ * @param {string} profile
214
+ * @param {Array<any>} roots
215
+ * @param {Array<any>} chain
216
+ * @param {string} principal
217
+ * @returns {number}
218
+ */
219
+ openService(lane, profile, roots, chain, principal) {
220
+ try {
221
+ const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
222
+ const ptr0 = passStringToWasm0(profile, wasm.__wbindgen_export2, wasm.__wbindgen_export3);
223
+ const len0 = WASM_VECTOR_LEN;
224
+ const ptr1 = passStringToWasm0(principal, wasm.__wbindgen_export2, wasm.__wbindgen_export3);
225
+ const len1 = WASM_VECTOR_LEN;
226
+ wasm.workerclient_openService(retptr, this.__wbg_ptr, lane, ptr0, len0, addBorrowedObject(roots), addBorrowedObject(chain), ptr1, len1);
227
+ var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
228
+ var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
229
+ var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
230
+ if (r2) {
231
+ throw takeObject(r1);
232
+ }
233
+ return r0 >>> 0;
234
+ } finally {
235
+ wasm.__wbindgen_add_to_stack_pointer(16);
236
+ heap[stack_pointer++] = void 0;
237
+ heap[stack_pointer++] = void 0;
238
+ }
239
+ }
178
240
  /**
179
241
  * Opens a session stream.
180
242
  * @param {number} computer
@@ -216,6 +278,45 @@ var WorkerClient = class {
216
278
  const len0 = WASM_VECTOR_LEN;
217
279
  wasm.workerclient_receive(this.__wbg_ptr, ptr0, len0, now);
218
280
  }
281
+ /**
282
+ * The plaintext a service connection received since the last read, as
283
+ * one batch, possibly empty; after a batch nothing more is read until
284
+ * `serviceRelease`.
285
+ * @param {number} service
286
+ * @returns {Uint8Array}
287
+ */
288
+ serviceRead(service) {
289
+ const ret = wasm.workerclient_serviceRead(this.__wbg_ptr, service);
290
+ return takeObject(ret);
291
+ }
292
+ /**
293
+ * The page has handled the last batch of a service connection; its
294
+ * stream is read again.
295
+ * @param {number} service
296
+ */
297
+ serviceRelease(service) {
298
+ wasm.workerclient_serviceRelease(this.__wbg_ptr, service);
299
+ }
300
+ /**
301
+ * Queues plaintext for a service connection.
302
+ * @param {number} service
303
+ * @param {Uint8Array} bytes
304
+ */
305
+ serviceWrite(service, bytes) {
306
+ try {
307
+ const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
308
+ const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_export2);
309
+ const len0 = WASM_VECTOR_LEN;
310
+ wasm.workerclient_serviceWrite(retptr, this.__wbg_ptr, service, ptr0, len0);
311
+ var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
312
+ var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
313
+ if (r1) {
314
+ throw takeObject(r0);
315
+ }
316
+ } finally {
317
+ wasm.__wbindgen_add_to_stack_pointer(16);
318
+ }
319
+ }
219
320
  /**
220
321
  * Takes the bytes to send to the edge.
221
322
  * @returns {Uint8Array}
@@ -741,6 +842,14 @@ function serveComputerConnections(scope) {
741
842
  }
742
843
  }
743
844
  }
845
+ for (const service of dock.services) {
846
+ const read = dock.client.serviceRead(service);
847
+ if (read.length > 0) {
848
+ post({ type: "service-data", dock: id, service, bytes: read }, [
849
+ read.buffer
850
+ ]);
851
+ }
852
+ }
744
853
  const more = dock.client.takeOutput();
745
854
  if (more.length > 0 && dock.socket.readyState === WebSocket.OPEN) {
746
855
  dock.socket.send(more);
@@ -766,8 +875,37 @@ function serveComputerConnections(scope) {
766
875
  const num = (value) => typeof value === "number" ? value : 0;
767
876
  switch (event["type"]) {
768
877
  case "docked":
769
- post({ type: "docked", dock: id });
878
+ post({
879
+ type: "docked",
880
+ dock: id,
881
+ serviceLaneProfile: text(event["serviceLaneProfile"])
882
+ });
883
+ return;
884
+ case "service-established":
885
+ post({
886
+ type: "service-established",
887
+ dock: id,
888
+ service: num(event["service"])
889
+ });
770
890
  return;
891
+ case "service-ended": {
892
+ const service = num(event["service"]);
893
+ const read = dock.client.serviceRead(service);
894
+ if (read.length > 0) {
895
+ post({ type: "service-data", dock: id, service, bytes: read }, [
896
+ read.buffer
897
+ ]);
898
+ }
899
+ dock.services.delete(service);
900
+ dock.client.closeService(service);
901
+ post({
902
+ type: "service-ended",
903
+ dock: id,
904
+ service,
905
+ reason: text(event["reason"])
906
+ });
907
+ return;
908
+ }
771
909
  case "drain":
772
910
  post({ type: "drain", dock: id, reason: text(event["reason"]) });
773
911
  return;
@@ -835,7 +973,13 @@ function serveComputerConnections(scope) {
835
973
  const socket = new WebSocket(request.url, SUBPROTOCOL);
836
974
  socket.binaryType = "arraybuffer";
837
975
  const id = nextDock++;
838
- const dock = { client, socket, streams: /* @__PURE__ */ new Map(), timer: void 0 };
976
+ const dock = {
977
+ client,
978
+ socket,
979
+ streams: /* @__PURE__ */ new Map(),
980
+ services: /* @__PURE__ */ new Set(),
981
+ timer: void 0
982
+ };
839
983
  docks.set(id, dock);
840
984
  socket.addEventListener("open", () => {
841
985
  turn(id, dock);
@@ -905,6 +1049,43 @@ function serveComputerConnections(scope) {
905
1049
  turn(request.dock, dock);
906
1050
  return computer;
907
1051
  }
1052
+ case "open-service-lane": {
1053
+ const dock = docked(request.dock);
1054
+ const lane = dock.client.openServiceLane(request.principal);
1055
+ turn(request.dock, dock);
1056
+ return lane;
1057
+ }
1058
+ case "open-service": {
1059
+ const dock = docked(request.dock);
1060
+ const service = dock.client.openService(
1061
+ request.lane,
1062
+ request.profile,
1063
+ [...request.roots],
1064
+ [...request.chain],
1065
+ request.principal
1066
+ );
1067
+ dock.services.add(service);
1068
+ turn(request.dock, dock);
1069
+ return service;
1070
+ }
1071
+ case "service-write": {
1072
+ const dock = docked(request.dock);
1073
+ dock.client.serviceWrite(request.service, request.bytes);
1074
+ turn(request.dock, dock);
1075
+ return void 0;
1076
+ }
1077
+ case "service-release": {
1078
+ const dock = docked(request.dock);
1079
+ dock.client.serviceRelease(request.service);
1080
+ turn(request.dock, dock);
1081
+ return void 0;
1082
+ }
1083
+ case "close-service": {
1084
+ const dock = docked(request.dock);
1085
+ dock.client.closeService(request.service);
1086
+ turn(request.dock, dock);
1087
+ return void 0;
1088
+ }
908
1089
  case "close-computer": {
909
1090
  const dock = docked(request.dock);
910
1091
  dock.client.closeComputer(request.computer);