withruntime 0.28.0 → 1.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.
Files changed (66) hide show
  1. checksums.yaml +4 -4
  2. data/lib/withruntime/generated/apps.rb +192 -0
  3. data/lib/withruntime/generated/audit.rb +78 -0
  4. data/lib/withruntime/generated/browsers.rb +192 -0
  5. data/lib/withruntime/generated/builds.rb +192 -0
  6. data/lib/withruntime/generated/ci.rb +192 -0
  7. data/lib/withruntime/generated/containers.rb +192 -0
  8. data/lib/withruntime/generated/desktops.rb +192 -0
  9. data/lib/withruntime/generated/domains.rb +152 -0
  10. data/lib/withruntime/generated/egress_ips.rb +81 -0
  11. data/lib/withruntime/generated/events.rb +60 -0
  12. data/lib/withruntime/generated/feedback.rb +96 -0
  13. data/lib/withruntime/generated/functions.rb +192 -0
  14. data/lib/withruntime/generated/identities.rb +68 -0
  15. data/lib/withruntime/generated/images.rb +391 -0
  16. data/lib/withruntime/generated/job_runs.rb +110 -0
  17. data/lib/withruntime/generated/jobs.rb +333 -0
  18. data/lib/withruntime/generated/keys.rb +261 -0
  19. data/lib/withruntime/generated/kit.rb +111 -0
  20. data/lib/withruntime/generated/me.rb +69 -0
  21. data/lib/withruntime/generated/networks.rb +72 -0
  22. data/lib/withruntime/generated/notebooks.rb +192 -0
  23. data/lib/withruntime/generated/otel.rb +94 -0
  24. data/lib/withruntime/generated/ports.rb +118 -0
  25. data/lib/withruntime/generated/previews.rb +124 -0
  26. data/lib/withruntime/generated/projects.rb +108 -0
  27. data/lib/withruntime/generated/roles.rb +68 -0
  28. data/lib/withruntime/generated/routes.rb +11 -0
  29. data/lib/withruntime/generated/runtime.rb +188 -0
  30. data/lib/withruntime/generated/sandboxes.rb +1835 -0
  31. data/lib/withruntime/generated/secrets.rb +294 -0
  32. data/lib/withruntime/generated/sessions.rb +143 -0
  33. data/lib/withruntime/generated/sites.rb +192 -0
  34. data/lib/withruntime/generated/snapshots.rb +32 -0
  35. data/lib/withruntime/generated/tunnels.rb +165 -0
  36. data/lib/withruntime/generated/usage.rb +287 -0
  37. data/lib/withruntime/generated/volumes.rb +61 -0
  38. data/lib/withruntime/generated/webhooks.rb +91 -0
  39. data/lib/withruntime/generated/workspaces.rb +192 -0
  40. data/lib/withruntime/signing.rb +162 -0
  41. data/lib/withruntime/version.rb +2 -2
  42. data/lib/withruntime.rb +5 -43
  43. metadata +45 -35
  44. data/lib/withruntime/agents.rb +0 -877
  45. data/lib/withruntime/api_defaults.rb +0 -17
  46. data/lib/withruntime/apps.rb +0 -377
  47. data/lib/withruntime/browsers.rb +0 -104
  48. data/lib/withruntime/builds.rb +0 -218
  49. data/lib/withruntime/ci.rb +0 -164
  50. data/lib/withruntime/client.rb +0 -140
  51. data/lib/withruntime/containers.rb +0 -39
  52. data/lib/withruntime/credentials.rb +0 -111
  53. data/lib/withruntime/fields.rb +0 -40
  54. data/lib/withruntime/file_watch.rb +0 -73
  55. data/lib/withruntime/images.rb +0 -258
  56. data/lib/withruntime/network_products.rb +0 -49
  57. data/lib/withruntime/parity_products.rb +0 -51
  58. data/lib/withruntime/products.rb +0 -560
  59. data/lib/withruntime/record.rb +0 -99
  60. data/lib/withruntime/reservations.rb +0 -76
  61. data/lib/withruntime/sandbox.rb +0 -775
  62. data/lib/withruntime/tar.rb +0 -292
  63. data/lib/withruntime/transport.rb +0 -575
  64. data/lib/withruntime/tunnel.rb +0 -275
  65. data/lib/withruntime/wallet.rb +0 -68
  66. data/lib/withruntime/websocket.rb +0 -384
@@ -0,0 +1,1835 @@
1
+ # Generated by spec-gen from engines/front/crates/spec. Do not edit:
2
+ # change the spec and run `cargo run -p runtime-front-spec-gen -- write`.
3
+
4
+ require "uri"
5
+ require_relative "runtime"
6
+
7
+ module Withruntime
8
+ module Generated
9
+ # A command a machine starts at every fresh boot.
10
+ # - +cmd+: The command: text, run by `bash -lc`, or the program and its arguments as a list, run without a shell.
11
+ # - +cwd+: The directory it runs in; the user's home when omitted.
12
+ # - +env+: Environment variables to add.
13
+ # - +ready_port+: A port it listens on once ready: a create answers once something listens there. At least 1. At most 65535.
14
+ # - +ready_command+: A shell command that exits 0 once it is ready, run by `/bin/sh -c` in `cwd` until it does: a create answers once it has.
15
+ # - +ready_timeout_seconds+: How long a create waits for `readyPort` or `readyCommand`, 1 to 300 seconds: 60 when omitted. At least 1. At most 300.
16
+ MachineStart = Struct.new(:cmd, :cwd, :env, :ready_port, :ready_command, :ready_timeout_seconds, keyword_init: true) do
17
+ def self.from(h)
18
+ return nil if h.nil?
19
+
20
+ new(
21
+ cmd: h["cmd"],
22
+ cwd: h["cwd"],
23
+ env: h["env"],
24
+ ready_port: h["readyPort"],
25
+ ready_command: h["readyCommand"],
26
+ ready_timeout_seconds: h["readyTimeoutSeconds"],
27
+ )
28
+ end
29
+
30
+ def to_wire
31
+ {
32
+ "cmd" => self.cmd,
33
+ "cwd" => self.cwd,
34
+ "env" => self.env,
35
+ "readyPort" => self.ready_port,
36
+ "readyCommand" => self.ready_command,
37
+ "readyTimeoutSeconds" => self.ready_timeout_seconds,
38
+ }.compact
39
+ end
40
+ end
41
+
42
+ # A volume a machine attaches at its create, mounted read-write in it, one machine at a time; detached when the machine is deleted.
43
+ # - +volume+: The volume, by name or ID, in the machine's project.
44
+ # - +path+: Where it is mounted, such as `/data`: an absolute path, not under `/proc`, `/sys`, `/dev`, `/etc`, `/usr`, `/bin`, `/sbin`, `/lib` or `/boot`.
45
+ VolumeMount = Struct.new(:volume, :path, keyword_init: true) do
46
+ def self.from(h)
47
+ return nil if h.nil?
48
+
49
+ new(
50
+ volume: h["volume"],
51
+ path: h["path"],
52
+ )
53
+ end
54
+
55
+ def to_wire
56
+ {
57
+ "volume" => self.volume,
58
+ "path" => self.path,
59
+ }.compact
60
+ end
61
+ end
62
+
63
+ # A command a sandbox runs once it starts: when it ends, the sandbox stops.
64
+ # - +cmd+: The command: text, run by `bash -lc`, or the program and its arguments as a list, run without a shell.
65
+ # - +cwd+: The directory it runs in; the user's home when omitted.
66
+ # - +env+: Environment variables to add.
67
+ # - +timeout_seconds+: Seconds it may run before it is stopped (`1.5` for 1,500 ms); no limit when omitted or 0. At least 0.
68
+ SandboxRun = Struct.new(:cmd, :cwd, :env, :timeout_seconds, keyword_init: true) do
69
+ def self.from(h)
70
+ return nil if h.nil?
71
+
72
+ new(
73
+ cmd: h["cmd"],
74
+ cwd: h["cwd"],
75
+ env: h["env"],
76
+ timeout_seconds: h["timeoutSeconds"],
77
+ )
78
+ end
79
+
80
+ def to_wire
81
+ {
82
+ "cmd" => self.cmd,
83
+ "cwd" => self.cwd,
84
+ "env" => self.env,
85
+ "timeoutSeconds" => self.timeout_seconds,
86
+ }.compact
87
+ end
88
+ end
89
+
90
+ # Where a sandbox may connect out, past the walls every machine has.
91
+ # - +allow_outbound+: The only places it may reach, each a host, `*.` and a name for every name under it, an address or a CIDR (`[` and `]` around an IPv6 address), every port when it names none; `:port` for that port alone, on a host name for a port beyond 80 and 443, which go together. `*` is every public host. Every public host when omitted; nothing when empty.
92
+ # - +deny_outbound+: Places it may never reach, written as in allowOutbound with no port: a deny wins over every allow.
93
+ NetworkRules = Struct.new(:allow_outbound, :deny_outbound, keyword_init: true) do
94
+ def self.from(h)
95
+ return nil if h.nil?
96
+
97
+ new(
98
+ allow_outbound: h["allowOutbound"],
99
+ deny_outbound: h["denyOutbound"],
100
+ )
101
+ end
102
+
103
+ def to_wire
104
+ {
105
+ "allowOutbound" => self.allow_outbound,
106
+ "denyOutbound" => self.deny_outbound,
107
+ }.compact
108
+ end
109
+ end
110
+
111
+ # A sandbox's settings: what a create sets on its machine.
112
+ # - +vcpu+: Its vCPUs. At least 1. Default: 2.
113
+ # - +memory_gb+: Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (`1.5`). At least 1. Default: 4.
114
+ # - +disk_gb+: Its disk in GB (1 GB is 1,024 MiB), to the MiB. At least 1. Default: 4.
115
+ # - +image+: The image it boots, by name (its newest version), `name:version` or ID; Runtime's default image when omitted.
116
+ # - +secrets+: The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. At most 64 items.
117
+ # - +start+: The command it starts at every fresh boot and keeps running, as a service: a web server, a runner, a desktop. A wake with its memory kept does not start it again. Its image's when omitted.
118
+ # - +user+: Who every command, process, terminal and code run in it runs as when the call names no `user`: `runtime` (uid 1000, with passwordless sudo) or `root`. Its image's when omitted, else `runtime`.
119
+ SandboxSettings = Struct.new(:vcpu, :memory_gb, :disk_gb, :image, :secrets, :start, :user, keyword_init: true) do
120
+ def self.from(h)
121
+ return nil if h.nil?
122
+
123
+ new(
124
+ vcpu: h["vcpu"],
125
+ memory_gb: h["memoryGB"],
126
+ disk_gb: h["diskGB"],
127
+ image: h["image"],
128
+ secrets: h["secrets"],
129
+ start: MachineStart.from(h["start"]),
130
+ user: h["user"],
131
+ )
132
+ end
133
+
134
+ def to_wire
135
+ {
136
+ "vcpu" => self.vcpu,
137
+ "memoryGB" => self.memory_gb,
138
+ "diskGB" => self.disk_gb,
139
+ "image" => self.image,
140
+ "secrets" => self.secrets,
141
+ "start" => self.start&.to_wire,
142
+ "user" => self.user,
143
+ }.compact
144
+ end
145
+ end
146
+
147
+ # A sandbox to create.
148
+ # - +vcpu+: Its vCPUs. At least 1. Default: 2.
149
+ # - +memory_gb+: Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (`1.5`). At least 1. Default: 4.
150
+ # - +disk_gb+: Its disk in GB (1 GB is 1,024 MiB), to the MiB. At least 1. Default: 4.
151
+ # - +image+: The image it boots, by name (its newest version), `name:version` or ID; Runtime's default image when omitted.
152
+ # - +secrets+: The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. At most 64 items.
153
+ # - +start+: The command it starts at every fresh boot and keeps running, as a service: a web server, a runner, a desktop. A wake with its memory kept does not start it again. Its image's when omitted.
154
+ # - +user+: Who every command, process, terminal and code run in it runs as when the call names no `user`: `runtime` (uid 1000, with passwordless sudo) or `root`. Its image's when omitted, else `runtime`.
155
+ # - +volumes+: Volumes it attaches and mounts at its create, at most one; detached when it is deleted, to attach to another.
156
+ # - +run+: A command it runs once it starts. When the command ends, the sandbox is `paused` with its disk kept (exitCode says how it ended) and a call starts it again. Needs the `exec` permission too.
157
+ # - +name+: Its name, unique in its project.
158
+ # - +labels+: Labels to find it by.
159
+ # - +get_or_create+: With a name: the sandbox of that name when there is one, else a new one.
160
+ # - +max_cost+: The most it may cost in all, in US dollars (`"5.00"`): once it has cost that it pauses, and starts again only once its maxCost is raised (`update`); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave.
161
+ # - +idle_pause_seconds+: Seconds with nothing happening before it pauses, 60 to 86400; 0 never; 300 when omitted. A fork keeps its source's, except 0: a copy never pauses only when its fork asks. At least 0. At most 86400.
162
+ # - +snapshot+: A snapshot it starts as: a copy of it running, at its sizes, in its project, with its secrets.
163
+ # - +network+: Where it may connect out from its first start, as setNetwork takes it; the open internet behind every machine's walls when omitted.
164
+ # - +env+: Environment variables for every command and process in it and its start, at most 32 and 32768 bytes of names and values; values are never answered. A copy keeps them.
165
+ SandboxCreate = Struct.new(:vcpu, :memory_gb, :disk_gb, :image, :secrets, :start, :user, :volumes, :run, :name, :labels, :get_or_create, :max_cost, :idle_pause_seconds, :snapshot, :network, :env, keyword_init: true) do
166
+ def self.from(h)
167
+ return nil if h.nil?
168
+
169
+ new(
170
+ vcpu: h["vcpu"],
171
+ memory_gb: h["memoryGB"],
172
+ disk_gb: h["diskGB"],
173
+ image: h["image"],
174
+ secrets: h["secrets"],
175
+ start: MachineStart.from(h["start"]),
176
+ user: h["user"],
177
+ volumes: h["volumes"]&.map { |i| VolumeMount.from(i) },
178
+ run: SandboxRun.from(h["run"]),
179
+ name: h["name"],
180
+ labels: h["labels"],
181
+ get_or_create: h["getOrCreate"],
182
+ max_cost: h["maxCost"],
183
+ idle_pause_seconds: h["idlePauseSeconds"],
184
+ snapshot: h["snapshot"],
185
+ network: NetworkRules.from(h["network"]),
186
+ env: h["env"],
187
+ )
188
+ end
189
+
190
+ def to_wire
191
+ {
192
+ "vcpu" => self.vcpu,
193
+ "memoryGB" => self.memory_gb,
194
+ "diskGB" => self.disk_gb,
195
+ "image" => self.image,
196
+ "secrets" => self.secrets,
197
+ "start" => self.start&.to_wire,
198
+ "user" => self.user,
199
+ "volumes" => self.volumes&.map { |i| i&.to_wire },
200
+ "run" => self.run&.to_wire,
201
+ "name" => self.name,
202
+ "labels" => self.labels,
203
+ "getOrCreate" => self.get_or_create,
204
+ "maxCost" => self.max_cost,
205
+ "idlePauseSeconds" => self.idle_pause_seconds,
206
+ "snapshot" => self.snapshot,
207
+ "network" => self.network&.to_wire,
208
+ "env" => self.env,
209
+ }.compact
210
+ end
211
+ end
212
+
213
+ # How a create's wait for its start's ready check (`start.readyPort`, `start.readyCommand`) went.
214
+ # - +state+: `ready` (the check passed), `timeout` (not within `readyTimeoutSeconds`), or `not_running` (it never ran).
215
+ # - +waited_ms+: How long it waited, in milliseconds.
216
+ MachineReady = Struct.new(:state, :waited_ms, keyword_init: true) do
217
+ def self.from(h)
218
+ return nil if h.nil?
219
+
220
+ new(
221
+ state: h["state"],
222
+ waited_ms: h["waitedMs"],
223
+ )
224
+ end
225
+
226
+ def to_wire
227
+ {
228
+ "state" => self.state,
229
+ "waitedMs" => self.waited_ms,
230
+ }.compact
231
+ end
232
+ end
233
+
234
+ # A sandbox.
235
+ # - +vcpu+: Its vCPUs. At least 1. Default: 2.
236
+ # - +memory_gb+: Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (`1.5`). At least 1. Default: 4.
237
+ # - +disk_gb+: Its disk in GB (1 GB is 1,024 MiB), to the MiB. At least 1. Default: 4.
238
+ # - +image+: The image it boots, by name (its newest version), `name:version` or ID; Runtime's default image when omitted.
239
+ # - +secrets+: The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. At most 64 items.
240
+ # - +start+: The command it starts at every fresh boot and keeps running, as a service: a web server, a runner, a desktop. A wake with its memory kept does not start it again. Its image's when omitted.
241
+ # - +user+: Who every command, process, terminal and code run in it runs as when the call names no `user`: `runtime` (uid 1000, with passwordless sudo) or `root`. Its image's when omitted, else `runtime`.
242
+ # - +id+: Its ID.
243
+ # - +object+: Always `sandbox`.
244
+ # - +name+: Its name, unique in its project.
245
+ # - +state+: Where it is.
246
+ # - +labels+: Its labels.
247
+ # - +created_at+: When it was created.
248
+ # - +deleted_at+: When it was deleted: a delete's answer alone.
249
+ # - +revision+: Its revision, changed by every change to it: what an update's If-Match names.
250
+ # - +idle_pause_seconds+: Seconds with nothing happening before it pauses; 0 never. Default: 300.
251
+ # - +max_cost+: The most it may cost in all, in US dollars; none when it has no such cap.
252
+ # - +exit_code+: Its run's exit code, once its run ended; none for one a signal or its timeout ended.
253
+ # - +ended_at+: When its run ended.
254
+ # - +ready+: A create's answer alone, for a start with a ready check: how its wait went.
255
+ Sandbox = Struct.new(:vcpu, :memory_gb, :disk_gb, :image, :secrets, :start, :user, :id, :object, :name, :state, :labels, :created_at, :deleted_at, :revision, :idle_pause_seconds, :max_cost, :exit_code, :ended_at, :ready, keyword_init: true) do
256
+ def self.from(h)
257
+ return nil if h.nil?
258
+
259
+ new(
260
+ vcpu: h["vcpu"],
261
+ memory_gb: h["memoryGB"],
262
+ disk_gb: h["diskGB"],
263
+ image: h["image"],
264
+ secrets: h["secrets"],
265
+ start: MachineStart.from(h["start"]),
266
+ user: h["user"],
267
+ id: h["id"],
268
+ object: h["object"],
269
+ name: h["name"],
270
+ state: h["state"],
271
+ labels: h["labels"],
272
+ created_at: h["createdAt"],
273
+ deleted_at: h["deletedAt"],
274
+ revision: h["revision"],
275
+ idle_pause_seconds: h["idlePauseSeconds"],
276
+ max_cost: h["maxCost"],
277
+ exit_code: h["exitCode"],
278
+ ended_at: h["endedAt"],
279
+ ready: MachineReady.from(h["ready"]),
280
+ )
281
+ end
282
+
283
+ def to_wire
284
+ {
285
+ "vcpu" => self.vcpu,
286
+ "memoryGB" => self.memory_gb,
287
+ "diskGB" => self.disk_gb,
288
+ "image" => self.image,
289
+ "secrets" => self.secrets,
290
+ "start" => self.start&.to_wire,
291
+ "user" => self.user,
292
+ "id" => self.id,
293
+ "object" => self.object,
294
+ "name" => self.name,
295
+ "state" => self.state,
296
+ "labels" => self.labels,
297
+ "createdAt" => self.created_at,
298
+ "deletedAt" => self.deleted_at,
299
+ "revision" => self.revision,
300
+ "idlePauseSeconds" => self.idle_pause_seconds,
301
+ "maxCost" => self.max_cost,
302
+ "exitCode" => self.exit_code,
303
+ "endedAt" => self.ended_at,
304
+ "ready" => self.ready&.to_wire,
305
+ }.compact
306
+ end
307
+ end
308
+
309
+ # A terminal's size.
310
+ # - +cols+: Its columns. At least 1. At most 65535.
311
+ # - +rows+: Its rows. At least 1. At most 65535.
312
+ Terminal = Struct.new(:cols, :rows, keyword_init: true) do
313
+ def self.from(h)
314
+ return nil if h.nil?
315
+
316
+ new(
317
+ cols: h["cols"],
318
+ rows: h["rows"],
319
+ )
320
+ end
321
+
322
+ def to_wire
323
+ {
324
+ "cols" => self.cols,
325
+ "rows" => self.rows,
326
+ }.compact
327
+ end
328
+ end
329
+
330
+ # A command to run: to its end, or started and answered at once (`wait: false`).
331
+ # - +cmd+: The command: text, run by `bash -lc` (`"npm test"`), or a list, the program and its arguments run without a shell (`["npm", "test"]`).
332
+ # - +cwd+: The directory it runs in; the user's home when omitted.
333
+ # - +env+: Environment variables to add.
334
+ # - +stdin+: Bytes sent to its standard input.
335
+ # - +timeout_seconds+: Seconds it may run before it is stopped (`1.5` for 1,500 ms); it runs to its end when omitted or 0. At least 0.
336
+ # - +stream+: Answer as NDJSON events while it runs (start, stdout, stderr, exit), as `Accept: application/x-ndjson` does.
337
+ # - +wait+: Wait for it to end and return it with its output. False returns it at once, running: read its output with processes.output, send it input with processes.write and signals with processes.signal. Default: true.
338
+ # - +stdin_open+: Keep its standard input open for processes.write; not with stdin, and not with a wait for its end.
339
+ # - +output_encoding+: How processes.output answers its output. Default: "utf8".
340
+ # - +pty+: Run it on a terminal of this size: its input, output and controlling terminal; not with a wait for its end.
341
+ # - +user+: Who it runs as: `runtime` (uid 1000, with passwordless sudo) or `root`; the sandbox's `user` when omitted.
342
+ ExecRequest = Struct.new(:cmd, :cwd, :env, :stdin, :timeout_seconds, :stream, :wait, :stdin_open, :output_encoding, :pty, :user, keyword_init: true) do
343
+ def self.from(h)
344
+ return nil if h.nil?
345
+
346
+ new(
347
+ cmd: h["cmd"],
348
+ cwd: h["cwd"],
349
+ env: h["env"],
350
+ stdin: h["stdin"],
351
+ timeout_seconds: h["timeoutSeconds"],
352
+ stream: h["stream"],
353
+ wait: h["wait"],
354
+ stdin_open: h["stdinOpen"],
355
+ output_encoding: h["outputEncoding"],
356
+ pty: Terminal.from(h["pty"]),
357
+ user: h["user"],
358
+ )
359
+ end
360
+
361
+ def to_wire
362
+ {
363
+ "cmd" => self.cmd,
364
+ "cwd" => self.cwd,
365
+ "env" => self.env,
366
+ "stdin" => self.stdin,
367
+ "timeoutSeconds" => self.timeout_seconds,
368
+ "stream" => self.stream,
369
+ "wait" => self.wait,
370
+ "stdinOpen" => self.stdin_open,
371
+ "outputEncoding" => self.output_encoding,
372
+ "pty" => self.pty&.to_wire,
373
+ "user" => self.user,
374
+ }.compact
375
+ end
376
+ end
377
+
378
+ # A process.
379
+ # - +id+: Its ID.
380
+ # - +object+: Always `process`.
381
+ # - +state+: Where it is.
382
+ # - +exit_code+: Its exit code once it exited; negative when a signal ended it.
383
+ # - +command+: The command it runs.
384
+ # - +cwd+: The directory it runs in.
385
+ # - +pty+: It runs on a terminal.
386
+ # - +stdin_open+: Its standard input is open for processes.write.
387
+ # - +stdin_offset+: Bytes of input it has taken.
388
+ # - +output_encoding+: How its output is answered.
389
+ # - +started_at+: When it started.
390
+ # - +ended_at+: When it ended.
391
+ # - +timeout_seconds+: Seconds it may run before it is killed.
392
+ # - +output_bytes+: Bytes of output it has written: the cursor past its last.
393
+ # - +first_offset+: The oldest byte of its output still kept.
394
+ # - +stdout+: What it wrote to standard output, as UTF-8: given once an exec waited for its end.
395
+ # - +stderr+: What it wrote to standard error, as UTF-8: given once an exec waited for its end.
396
+ # - +stdout_truncated+: stdout holds only part of what it wrote (its first 1 MiB).
397
+ # - +stderr_truncated+: stderr holds only part of what it wrote (its first 1 MiB).
398
+ # - +duration_seconds+: How long it ran, in seconds, to the millisecond, once it ended.
399
+ Process = Struct.new(:id, :object, :state, :exit_code, :command, :cwd, :pty, :stdin_open, :stdin_offset, :output_encoding, :started_at, :ended_at, :timeout_seconds, :output_bytes, :first_offset, :stdout, :stderr, :stdout_truncated, :stderr_truncated, :duration_seconds, keyword_init: true) do
400
+ def self.from(h)
401
+ return nil if h.nil?
402
+
403
+ new(
404
+ id: h["id"],
405
+ object: h["object"],
406
+ state: h["state"],
407
+ exit_code: h["exitCode"],
408
+ command: h["command"],
409
+ cwd: h["cwd"],
410
+ pty: h["pty"],
411
+ stdin_open: h["stdinOpen"],
412
+ stdin_offset: h["stdinOffset"],
413
+ output_encoding: h["outputEncoding"],
414
+ started_at: h["startedAt"],
415
+ ended_at: h["endedAt"],
416
+ timeout_seconds: h["timeoutSeconds"],
417
+ output_bytes: h["outputBytes"],
418
+ first_offset: h["firstOffset"],
419
+ stdout: h["stdout"],
420
+ stderr: h["stderr"],
421
+ stdout_truncated: h["stdoutTruncated"],
422
+ stderr_truncated: h["stderrTruncated"],
423
+ duration_seconds: h["durationSeconds"],
424
+ )
425
+ end
426
+
427
+ def to_wire
428
+ {
429
+ "id" => self.id,
430
+ "object" => self.object,
431
+ "state" => self.state,
432
+ "exitCode" => self.exit_code,
433
+ "command" => self.command,
434
+ "cwd" => self.cwd,
435
+ "pty" => self.pty,
436
+ "stdinOpen" => self.stdin_open,
437
+ "stdinOffset" => self.stdin_offset,
438
+ "outputEncoding" => self.output_encoding,
439
+ "startedAt" => self.started_at,
440
+ "endedAt" => self.ended_at,
441
+ "timeoutSeconds" => self.timeout_seconds,
442
+ "outputBytes" => self.output_bytes,
443
+ "firstOffset" => self.first_offset,
444
+ "stdout" => self.stdout,
445
+ "stderr" => self.stderr,
446
+ "stdoutTruncated" => self.stdout_truncated,
447
+ "stderrTruncated" => self.stderr_truncated,
448
+ "durationSeconds" => self.duration_seconds,
449
+ }.compact
450
+ end
451
+ end
452
+
453
+ # A file written.
454
+ # - +path+: Its path.
455
+ # - +size+: Its size in bytes, after the write.
456
+ # - +sha256+: Its SHA-256 in hex: given for a file written whole.
457
+ # - +offset+: Where the bytes were written: given for a write at an offset.
458
+ FileWritten = Struct.new(:path, :size, :sha256, :offset, keyword_init: true) do
459
+ def self.from(h)
460
+ return nil if h.nil?
461
+
462
+ new(
463
+ path: h["path"],
464
+ size: h["size"],
465
+ sha256: h["sha256"],
466
+ offset: h["offset"],
467
+ )
468
+ end
469
+
470
+ def to_wire
471
+ {
472
+ "path" => self.path,
473
+ "size" => self.size,
474
+ "sha256" => self.sha256,
475
+ "offset" => self.offset,
476
+ }.compact
477
+ end
478
+ end
479
+
480
+ # Some of a process's output.
481
+ # - +offset+: Where it starts in the process's output.
482
+ # - +stream+: The stream it was written to.
483
+ # - +text+: It, as text.
484
+ # - +base64+: It, as bytes, when the process answers base64.
485
+ OutputChunk = Struct.new(:offset, :stream, :text, :base64, keyword_init: true) do
486
+ def self.from(h)
487
+ return nil if h.nil?
488
+
489
+ new(
490
+ offset: h["offset"],
491
+ stream: h["stream"],
492
+ text: h["text"],
493
+ base64: h["base64"],
494
+ )
495
+ end
496
+
497
+ def to_wire
498
+ {
499
+ "offset" => self.offset,
500
+ "stream" => self.stream,
501
+ "text" => self.text,
502
+ "base64" => self.base64,
503
+ }.compact
504
+ end
505
+ end
506
+
507
+ # A process's output after a cursor.
508
+ # - +chunks+: The output, in the order it was written.
509
+ # - +next_cursor+: The cursor to read on from.
510
+ # - +truncated+: Output past the cursor was dropped before it was read.
511
+ # - +dropped_bytes+: How many bytes were dropped.
512
+ # - +process+: The process.
513
+ ProcessOutput = Struct.new(:chunks, :next_cursor, :truncated, :dropped_bytes, :process, keyword_init: true) do
514
+ def self.from(h)
515
+ return nil if h.nil?
516
+
517
+ new(
518
+ chunks: h["chunks"]&.map { |i| OutputChunk.from(i) },
519
+ next_cursor: h["nextCursor"],
520
+ truncated: h["truncated"],
521
+ dropped_bytes: h["droppedBytes"],
522
+ process: Process.from(h["process"]),
523
+ )
524
+ end
525
+
526
+ def to_wire
527
+ {
528
+ "chunks" => self.chunks&.map { |i| i&.to_wire },
529
+ "nextCursor" => self.next_cursor,
530
+ "truncated" => self.truncated,
531
+ "droppedBytes" => self.dropped_bytes,
532
+ "process" => self.process&.to_wire,
533
+ }.compact
534
+ end
535
+ end
536
+
537
+ # Input to send a process.
538
+ # - +data+: The bytes.
539
+ # - +offset+: Bytes of input sent before these (its stdinOffset): a resend is then never taken twice. They go after every other write when omitted.
540
+ # - +eof+: Close its input after these (^D on a terminal).
541
+ ProcessInput = Struct.new(:data, :offset, :eof, keyword_init: true) do
542
+ def self.from(h)
543
+ return nil if h.nil?
544
+
545
+ new(
546
+ data: h["data"],
547
+ offset: h["offset"],
548
+ eof: h["eof"],
549
+ )
550
+ end
551
+
552
+ def to_wire
553
+ {
554
+ "data" => self.data,
555
+ "offset" => self.offset,
556
+ "eof" => self.eof,
557
+ }.compact
558
+ end
559
+ end
560
+
561
+ # Input a process took.
562
+ # - +offset+: Bytes of input it has taken in all.
563
+ # - +process+: The process.
564
+ ProcessWritten = Struct.new(:offset, :process, keyword_init: true) do
565
+ def self.from(h)
566
+ return nil if h.nil?
567
+
568
+ new(
569
+ offset: h["offset"],
570
+ process: Process.from(h["process"]),
571
+ )
572
+ end
573
+
574
+ def to_wire
575
+ {
576
+ "offset" => self.offset,
577
+ "process" => self.process&.to_wire,
578
+ }.compact
579
+ end
580
+ end
581
+
582
+ # A signal to send a process and its group.
583
+ # - +signal+: The signal; SIGTERM when omitted.
584
+ ProcessSignal = Struct.new(:signal, keyword_init: true) do
585
+ def self.from(h)
586
+ return nil if h.nil?
587
+
588
+ new(
589
+ signal: h["signal"],
590
+ )
591
+ end
592
+
593
+ def to_wire
594
+ {
595
+ "signal" => self.signal,
596
+ }.compact
597
+ end
598
+ end
599
+
600
+ # A machine's processes, newest first.
601
+ # - +items+: Each process.
602
+ ProcessList = Struct.new(:items, keyword_init: true) do
603
+ def self.from(h)
604
+ return nil if h.nil?
605
+
606
+ new(
607
+ items: h["items"]&.map { |i| Process.from(i) },
608
+ )
609
+ end
610
+
611
+ def to_wire
612
+ {
613
+ "items" => self.items&.map { |i| i&.to_wire },
614
+ }.compact
615
+ end
616
+ end
617
+
618
+ # A file, a link or a directory to remove.
619
+ # - +path+: Its path.
620
+ # - +recursive+: A directory with its contents; refused for a directory with contents when omitted.
621
+ FileRemove = Struct.new(:path, :recursive, keyword_init: true) do
622
+ def self.from(h)
623
+ return nil if h.nil?
624
+
625
+ new(
626
+ path: h["path"],
627
+ recursive: h["recursive"],
628
+ )
629
+ end
630
+
631
+ def to_wire
632
+ {
633
+ "path" => self.path,
634
+ "recursive" => self.recursive,
635
+ }.compact
636
+ end
637
+ end
638
+
639
+ # A file, a link or a directory removed.
640
+ # - +path+: Its path.
641
+ # - +removed+: It was there and is removed; false when it was missing.
642
+ FileRemoved = Struct.new(:path, :removed, keyword_init: true) do
643
+ def self.from(h)
644
+ return nil if h.nil?
645
+
646
+ new(
647
+ path: h["path"],
648
+ removed: h["removed"],
649
+ )
650
+ end
651
+
652
+ def to_wire
653
+ {
654
+ "path" => self.path,
655
+ "removed" => self.removed,
656
+ }.compact
657
+ end
658
+ end
659
+
660
+ # A path in a sandbox: what is there, if anything.
661
+ # - +path+: Its path.
662
+ # - +exists+: Something is there.
663
+ # - +name+: Its last part.
664
+ # - +type+: What it is: `file`, `directory`, `symlink` or `other`.
665
+ # - +size+: Its size in bytes.
666
+ # - +mode+: Its permissions, in octal (`0644`).
667
+ # - +modified_at+: When it last changed.
668
+ # - +uid+: Its owner's user ID.
669
+ # - +gid+: Its group's ID.
670
+ # - +symlink_target+: Where a link points.
671
+ # - +sha256+: A file's SHA-256 in hex, read from its bytes: given when asked (`sha256=true`).
672
+ FileInfo = Struct.new(:path, :exists, :name, :type, :size, :mode, :modified_at, :uid, :gid, :symlink_target, :sha256, keyword_init: true) do
673
+ def self.from(h)
674
+ return nil if h.nil?
675
+
676
+ new(
677
+ path: h["path"],
678
+ exists: h["exists"],
679
+ name: h["name"],
680
+ type: h["type"],
681
+ size: h["size"],
682
+ mode: h["mode"],
683
+ modified_at: h["modifiedAt"],
684
+ uid: h["uid"],
685
+ gid: h["gid"],
686
+ symlink_target: h["symlinkTarget"],
687
+ sha256: h["sha256"],
688
+ )
689
+ end
690
+
691
+ def to_wire
692
+ {
693
+ "path" => self.path,
694
+ "exists" => self.exists,
695
+ "name" => self.name,
696
+ "type" => self.type,
697
+ "size" => self.size,
698
+ "mode" => self.mode,
699
+ "modifiedAt" => self.modified_at,
700
+ "uid" => self.uid,
701
+ "gid" => self.gid,
702
+ "symlinkTarget" => self.symlink_target,
703
+ "sha256" => self.sha256,
704
+ }.compact
705
+ end
706
+ end
707
+
708
+ # What a directory holds, in path order.
709
+ # - +items+: Each entry.
710
+ # - +truncated+: There were more entries than limit.
711
+ FileList = Struct.new(:items, :truncated, keyword_init: true) do
712
+ def self.from(h)
713
+ return nil if h.nil?
714
+
715
+ new(
716
+ items: h["items"]&.map { |i| FileInfo.from(i) },
717
+ truncated: h["truncated"],
718
+ )
719
+ end
720
+
721
+ def to_wire
722
+ {
723
+ "items" => self.items&.map { |i| i&.to_wire },
724
+ "truncated" => self.truncated,
725
+ }.compact
726
+ end
727
+ end
728
+
729
+ # A folder unpacked.
730
+ # - +path+: The folder.
731
+ # - +received+: The archive's bytes tar took.
732
+ FolderUnpacked = Struct.new(:path, :received, keyword_init: true) do
733
+ def self.from(h)
734
+ return nil if h.nil?
735
+
736
+ new(
737
+ path: h["path"],
738
+ received: h["received"],
739
+ )
740
+ end
741
+
742
+ def to_wire
743
+ {
744
+ "path" => self.path,
745
+ "received" => self.received,
746
+ }.compact
747
+ end
748
+ end
749
+
750
+ # A folder upload to begin: a tar archive sent in parts, unpacked into a folder as they arrive.
751
+ # - +path+: The folder, absolute and plain, such as `/workspace/app`: made with its parents.
752
+ # - +gzip+: The archive is gzip-compressed (`.tar.gz`). Default: false.
753
+ # - +user+: Who unpacks it: `runtime` or `root`; the machine's `user` when omitted.
754
+ FolderUploadBegin = Struct.new(:path, :gzip, :user, keyword_init: true) do
755
+ def self.from(h)
756
+ return nil if h.nil?
757
+
758
+ new(
759
+ path: h["path"],
760
+ gzip: h["gzip"],
761
+ user: h["user"],
762
+ )
763
+ end
764
+
765
+ def to_wire
766
+ {
767
+ "path" => self.path,
768
+ "gzip" => self.gzip,
769
+ "user" => self.user,
770
+ }.compact
771
+ end
772
+ end
773
+
774
+ # A folder upload begun: its parts go to it in order, then its commit.
775
+ # - +upload_id+: Its ID, which its parts, its commit and its abort name.
776
+ # - +path+: The folder it unpacks into.
777
+ # - +gzip+: The archive is gzip-compressed.
778
+ # - +chunk_bytes+: The most bytes a part should carry.
779
+ FolderUpload = Struct.new(:upload_id, :path, :gzip, :chunk_bytes, keyword_init: true) do
780
+ def self.from(h)
781
+ return nil if h.nil?
782
+
783
+ new(
784
+ upload_id: h["uploadId"],
785
+ path: h["path"],
786
+ gzip: h["gzip"],
787
+ chunk_bytes: h["chunkBytes"],
788
+ )
789
+ end
790
+
791
+ def to_wire
792
+ {
793
+ "uploadId" => self.upload_id,
794
+ "path" => self.path,
795
+ "gzip" => self.gzip,
796
+ "chunkBytes" => self.chunk_bytes,
797
+ }.compact
798
+ end
799
+ end
800
+
801
+ # A folder upload's part taken.
802
+ # - +received+: The archive's bytes tar has taken so far: the next part's offset.
803
+ FolderUploadReceived = Struct.new(:received, keyword_init: true) do
804
+ def self.from(h)
805
+ return nil if h.nil?
806
+
807
+ new(
808
+ received: h["received"],
809
+ )
810
+ end
811
+
812
+ def to_wire
813
+ {
814
+ "received" => self.received,
815
+ }.compact
816
+ end
817
+ end
818
+
819
+ # A folder upload ended unfinished.
820
+ # - +aborted+: Always true: tar was stopped; what it unpacked stays.
821
+ FolderUploadAborted = Struct.new(:aborted, keyword_init: true) do
822
+ def self.from(h)
823
+ return nil if h.nil?
824
+
825
+ new(
826
+ aborted: h["aborted"],
827
+ )
828
+ end
829
+
830
+ def to_wire
831
+ {
832
+ "aborted" => self.aborted,
833
+ }.compact
834
+ end
835
+ end
836
+
837
+ # A directory to make.
838
+ # - +path+: Its path.
839
+ # - +parents+: Its parents are made too; true when omitted.
840
+ FileMkdir = Struct.new(:path, :parents, keyword_init: true) do
841
+ def self.from(h)
842
+ return nil if h.nil?
843
+
844
+ new(
845
+ path: h["path"],
846
+ parents: h["parents"],
847
+ )
848
+ end
849
+
850
+ def to_wire
851
+ {
852
+ "path" => self.path,
853
+ "parents" => self.parents,
854
+ }.compact
855
+ end
856
+ end
857
+
858
+ # A directory made.
859
+ # - +path+: Its path.
860
+ # - +created+: It was made; false when it was there already.
861
+ FileMade = Struct.new(:path, :created, keyword_init: true) do
862
+ def self.from(h)
863
+ return nil if h.nil?
864
+
865
+ new(
866
+ path: h["path"],
867
+ created: h["created"],
868
+ )
869
+ end
870
+
871
+ def to_wire
872
+ {
873
+ "path" => self.path,
874
+ "created" => self.created,
875
+ }.compact
876
+ end
877
+ end
878
+
879
+ # A file, a link or a directory to move.
880
+ # - +from+: Where it is.
881
+ # - +to+: Where it goes.
882
+ # - +overwrite+: Replace what is at `to`; refused 409 when something is there and this is omitted.
883
+ # - +sha256+: The file's SHA-256 in hex: only a file whose bytes hash to it moves. With it, a rename sent again after it moved returns the same answer.
884
+ # - +size+: The file's size in bytes: only a file of this size, every byte of it written, moves. At least 0.
885
+ FileRename = Struct.new(:from, :to, :overwrite, :sha256, :size, keyword_init: true) do
886
+ def self.from(h)
887
+ return nil if h.nil?
888
+
889
+ new(
890
+ from: h["from"],
891
+ to: h["to"],
892
+ overwrite: h["overwrite"],
893
+ sha256: h["sha256"],
894
+ size: h["size"],
895
+ )
896
+ end
897
+
898
+ def to_wire
899
+ {
900
+ "from" => self.from,
901
+ "to" => self.to,
902
+ "overwrite" => self.overwrite,
903
+ "sha256" => self.sha256,
904
+ "size" => self.size,
905
+ }.compact
906
+ end
907
+ end
908
+
909
+ # A file, a link or a directory moved.
910
+ # - +from+: Where it was.
911
+ # - +to+: Where it is now.
912
+ # - +size+: Its size in bytes: given for a move checked by sha256.
913
+ # - +sha256+: Its SHA-256 in hex: given for a move checked by sha256.
914
+ FileRenamed = Struct.new(:from, :to, :size, :sha256, keyword_init: true) do
915
+ def self.from(h)
916
+ return nil if h.nil?
917
+
918
+ new(
919
+ from: h["from"],
920
+ to: h["to"],
921
+ size: h["size"],
922
+ sha256: h["sha256"],
923
+ )
924
+ end
925
+
926
+ def to_wire
927
+ {
928
+ "from" => self.from,
929
+ "to" => self.to,
930
+ "size" => self.size,
931
+ "sha256" => self.sha256,
932
+ }.compact
933
+ end
934
+ end
935
+
936
+ # A file link to make: an expiring address for one file of a sandbox (or, with `archive`, a folder) that anyone may open with no API key.
937
+ # - +path+: The file's absolute path in the sandbox. For GET it must exist when the link is made.
938
+ # - +method+: `GET` (default): a download link. `PUT`: an upload link; the request's body becomes the file.
939
+ # - +expires_in_seconds+: How long the link works, in seconds. At least 60. At most 604800. Default: 3600.
940
+ # - +filename+: Download as this name (`Content-Disposition: attachment`). Without it a picture, video, sound or plain text shows in the browser; anything else downloads.
941
+ # - +max_bytes+: PUT only: the largest body the link takes, in bytes; 5 GiB by default and at most. At least 0. At most 5368709120.
942
+ # - +wake+: false: a paused sandbox is not woken for the link, which answers 409 `sandbox_paused`. Unset or true: it is woken.
943
+ # - +archive+: GET only: `path` is a folder, downloaded as a `.tar.gz`. Default: false.
944
+ FileLinkCreate = Struct.new(:path, :method, :expires_in_seconds, :filename, :max_bytes, :wake, :archive, keyword_init: true) do
945
+ def self.from(h)
946
+ return nil if h.nil?
947
+
948
+ new(
949
+ path: h["path"],
950
+ method: h["method"],
951
+ expires_in_seconds: h["expiresInSeconds"],
952
+ filename: h["filename"],
953
+ max_bytes: h["maxBytes"],
954
+ wake: h["wake"],
955
+ archive: h["archive"],
956
+ )
957
+ end
958
+
959
+ def to_wire
960
+ {
961
+ "path" => self.path,
962
+ "method" => self.method,
963
+ "expiresInSeconds" => self.expires_in_seconds,
964
+ "filename" => self.filename,
965
+ "maxBytes" => self.max_bytes,
966
+ "wake" => self.wake,
967
+ "archive" => self.archive,
968
+ }.compact
969
+ end
970
+ end
971
+
972
+ # A file link.
973
+ # - +url+: Its address, opened with no key: GET to download, PUT the file's bytes to upload.
974
+ # - +method+: `GET` or `PUT`.
975
+ # - +path+: The file's path in the sandbox.
976
+ # - +sandbox_id+: The sandbox.
977
+ # - +expires_at+: When it stops working.
978
+ # - +filename+: The name it downloads as.
979
+ # - +max_bytes+: The largest body an upload link takes.
980
+ # - +archive+: It downloads a folder as a `.tar.gz`.
981
+ FileLink = Struct.new(:url, :method, :path, :sandbox_id, :expires_at, :filename, :max_bytes, :archive, keyword_init: true) do
982
+ def self.from(h)
983
+ return nil if h.nil?
984
+
985
+ new(
986
+ url: h["url"],
987
+ method: h["method"],
988
+ path: h["path"],
989
+ sandbox_id: h["sandboxId"],
990
+ expires_at: h["expiresAt"],
991
+ filename: h["filename"],
992
+ max_bytes: h["maxBytes"],
993
+ archive: h["archive"],
994
+ )
995
+ end
996
+
997
+ def to_wire
998
+ {
999
+ "url" => self.url,
1000
+ "method" => self.method,
1001
+ "path" => self.path,
1002
+ "sandboxId" => self.sandbox_id,
1003
+ "expiresAt" => self.expires_at,
1004
+ "filename" => self.filename,
1005
+ "maxBytes" => self.max_bytes,
1006
+ "archive" => self.archive,
1007
+ }.compact
1008
+ end
1009
+ end
1010
+
1011
+ # A sandbox's file links ended.
1012
+ # - +sandbox_id+: The sandbox.
1013
+ # - +revoked_at+: When they ended: every link made before it.
1014
+ FileLinksRevoked = Struct.new(:sandbox_id, :revoked_at, keyword_init: true) do
1015
+ def self.from(h)
1016
+ return nil if h.nil?
1017
+
1018
+ new(
1019
+ sandbox_id: h["sandboxId"],
1020
+ revoked_at: h["revokedAt"],
1021
+ )
1022
+ end
1023
+
1024
+ def to_wire
1025
+ {
1026
+ "sandboxId" => self.sandbox_id,
1027
+ "revokedAt" => self.revoked_at,
1028
+ }.compact
1029
+ end
1030
+ end
1031
+
1032
+ # Where a sandbox may connect out.
1033
+ # - +allow_outbound+: The only places it may reach, each a host, `*.` and a name for every name under it, an address or a CIDR (`[` and `]` around an IPv6 address), every port when it names none; `:port` for that port alone, on a host name for a port beyond 80 and 443, which go together. `*` is every public host. Every public host when omitted; nothing when empty.
1034
+ # - +deny_outbound+: Places it may never reach, written as in allowOutbound with no port: a deny wins over every allow.
1035
+ # - +id+: The sandbox's ID.
1036
+ SandboxNetwork = Struct.new(:allow_outbound, :deny_outbound, :id, keyword_init: true) do
1037
+ def self.from(h)
1038
+ return nil if h.nil?
1039
+
1040
+ new(
1041
+ allow_outbound: h["allowOutbound"],
1042
+ deny_outbound: h["denyOutbound"],
1043
+ id: h["id"],
1044
+ )
1045
+ end
1046
+
1047
+ def to_wire
1048
+ {
1049
+ "allowOutbound" => self.allow_outbound,
1050
+ "denyOutbound" => self.deny_outbound,
1051
+ "id" => self.id,
1052
+ }.compact
1053
+ end
1054
+ end
1055
+
1056
+ # A machine's CPU and memory as its host measures them from the machine's own cgroup, never by a call into the machine, so reading them does not wake it or keep it awake. Either the current reading (over the host's last 5 seconds, with disk and pressure) or one step of a window (averaged over the time the machine ran in it).
1057
+ # - +at+: When it was read; for a step, where the step starts.
1058
+ # - +cpu_percent+: Its CPU, as a percent of all its vCPUs (0 to 100).
1059
+ # - +cpu_cores+: The same as a number of cores.
1060
+ # - +cpu_peak_percent+: Its busiest minute, as a percent of all its vCPUs.
1061
+ # - +cpu_wait_percent+: Percent of the last 10 seconds some task of it waited for a CPU.
1062
+ # - +memory_stall_percent+: Percent of the last 10 seconds some task of it waited for memory.
1063
+ # - +memory_bytes+: Memory it holds, in bytes: its resident memory on its host.
1064
+ # - +memory_peak_bytes+: The most memory it has held, in bytes; for a step, its highest minute's average.
1065
+ # - +samples+: How many measures it is made of: two reads for the reading now; for a step, the minutes the host measured it in.
1066
+ # - +disk_read_bytes_per_second+: Bytes its disks read a second.
1067
+ # - +disk_write_bytes_per_second+: Bytes its disks wrote a second.
1068
+ # - +disk_read_ops_per_second+: Reads its disks completed a second.
1069
+ # - +disk_write_ops_per_second+: Writes its disks completed a second.
1070
+ MetricPoint = Struct.new(:at, :cpu_percent, :cpu_cores, :cpu_peak_percent, :cpu_wait_percent, :memory_stall_percent, :memory_bytes, :memory_peak_bytes, :samples, :disk_read_bytes_per_second, :disk_write_bytes_per_second, :disk_read_ops_per_second, :disk_write_ops_per_second, keyword_init: true) do
1071
+ def self.from(h)
1072
+ return nil if h.nil?
1073
+
1074
+ new(
1075
+ at: h["at"],
1076
+ cpu_percent: h["cpuPercent"],
1077
+ cpu_cores: h["cpuCores"],
1078
+ cpu_peak_percent: h["cpuPeakPercent"],
1079
+ cpu_wait_percent: h["cpuWaitPercent"],
1080
+ memory_stall_percent: h["memoryStallPercent"],
1081
+ memory_bytes: h["memoryBytes"],
1082
+ memory_peak_bytes: h["memoryPeakBytes"],
1083
+ samples: h["samples"],
1084
+ disk_read_bytes_per_second: h["diskReadBytesPerSecond"],
1085
+ disk_write_bytes_per_second: h["diskWriteBytesPerSecond"],
1086
+ disk_read_ops_per_second: h["diskReadOpsPerSecond"],
1087
+ disk_write_ops_per_second: h["diskWriteOpsPerSecond"],
1088
+ )
1089
+ end
1090
+
1091
+ def to_wire
1092
+ {
1093
+ "at" => self.at,
1094
+ "cpuPercent" => self.cpu_percent,
1095
+ "cpuCores" => self.cpu_cores,
1096
+ "cpuPeakPercent" => self.cpu_peak_percent,
1097
+ "cpuWaitPercent" => self.cpu_wait_percent,
1098
+ "memoryStallPercent" => self.memory_stall_percent,
1099
+ "memoryBytes" => self.memory_bytes,
1100
+ "memoryPeakBytes" => self.memory_peak_bytes,
1101
+ "samples" => self.samples,
1102
+ "diskReadBytesPerSecond" => self.disk_read_bytes_per_second,
1103
+ "diskWriteBytesPerSecond" => self.disk_write_bytes_per_second,
1104
+ "diskReadOpsPerSecond" => self.disk_read_ops_per_second,
1105
+ "diskWriteOpsPerSecond" => self.disk_write_ops_per_second,
1106
+ }.compact
1107
+ end
1108
+ end
1109
+
1110
+ # A sandbox's CPU and memory over a time window, in steps, and its current reading (with disk and pressure) while it runs. Steps are returned in every state, including paused and stopped. Ranges: `15m` and `1h` in 60-second steps, `6h` in 120-second steps, `24h` in 480-second steps, `7d` and `30d` in 1-hour steps. Defaults to `1h`.
1111
+ # - +state+: Its state.
1112
+ # - +range+: The window asked for.
1113
+ # - +step_seconds+: The window's step, in seconds.
1114
+ # - +since+: Where the window starts: the start of the step that holds the range's start.
1115
+ # - +until+: Where it ends: now.
1116
+ # - +vcpu+: Its vCPUs.
1117
+ # - +memory_limit_bytes+: Its memory, in bytes.
1118
+ # - +disk_limit_bytes+: Its disk, in bytes.
1119
+ # - +latest+: The reading taken now; none when it is not running or its host could not read it.
1120
+ # - +points+: The window's steps, oldest first, each averaged over the time the sandbox ran in it. Steps in which it did not run are omitted. A minute appears about a minute after it ends; `latest` holds the current reading.
1121
+ MetricsBase = Struct.new(:state, :range, :step_seconds, :since, :until, :vcpu, :memory_limit_bytes, :disk_limit_bytes, :latest, :points, keyword_init: true) do
1122
+ def self.from(h)
1123
+ return nil if h.nil?
1124
+
1125
+ new(
1126
+ state: h["state"],
1127
+ range: h["range"],
1128
+ step_seconds: h["stepSeconds"],
1129
+ since: h["since"],
1130
+ until: h["until"],
1131
+ vcpu: h["vcpu"],
1132
+ memory_limit_bytes: h["memoryLimitBytes"],
1133
+ disk_limit_bytes: h["diskLimitBytes"],
1134
+ latest: MetricPoint.from(h["latest"]),
1135
+ points: h["points"]&.map { |i| MetricPoint.from(i) },
1136
+ )
1137
+ end
1138
+
1139
+ def to_wire
1140
+ {
1141
+ "state" => self.state,
1142
+ "range" => self.range,
1143
+ "stepSeconds" => self.step_seconds,
1144
+ "since" => self.since,
1145
+ "until" => self.until,
1146
+ "vcpu" => self.vcpu,
1147
+ "memoryLimitBytes" => self.memory_limit_bytes,
1148
+ "diskLimitBytes" => self.disk_limit_bytes,
1149
+ "latest" => self.latest&.to_wire,
1150
+ "points" => self.points&.map { |i| i&.to_wire },
1151
+ }.compact
1152
+ end
1153
+ end
1154
+
1155
+ # A sandbox's metrics.
1156
+ # - +state+: Its state.
1157
+ # - +range+: The window asked for.
1158
+ # - +step_seconds+: The window's step, in seconds.
1159
+ # - +since+: Where the window starts: the start of the step that holds the range's start.
1160
+ # - +until+: Where it ends: now.
1161
+ # - +vcpu+: Its vCPUs.
1162
+ # - +memory_limit_bytes+: Its memory, in bytes.
1163
+ # - +disk_limit_bytes+: Its disk, in bytes.
1164
+ # - +latest+: The reading taken now; none when it is not running or its host could not read it.
1165
+ # - +points+: The window's steps, oldest first, each averaged over the time the sandbox ran in it. Steps in which it did not run are omitted. A minute appears about a minute after it ends; `latest` holds the current reading.
1166
+ # - +id+: The sandbox's ID.
1167
+ SandboxMetrics = Struct.new(:state, :range, :step_seconds, :since, :until, :vcpu, :memory_limit_bytes, :disk_limit_bytes, :latest, :points, :id, keyword_init: true) do
1168
+ def self.from(h)
1169
+ return nil if h.nil?
1170
+
1171
+ new(
1172
+ state: h["state"],
1173
+ range: h["range"],
1174
+ step_seconds: h["stepSeconds"],
1175
+ since: h["since"],
1176
+ until: h["until"],
1177
+ vcpu: h["vcpu"],
1178
+ memory_limit_bytes: h["memoryLimitBytes"],
1179
+ disk_limit_bytes: h["diskLimitBytes"],
1180
+ latest: MetricPoint.from(h["latest"]),
1181
+ points: h["points"]&.map { |i| MetricPoint.from(i) },
1182
+ id: h["id"],
1183
+ )
1184
+ end
1185
+
1186
+ def to_wire
1187
+ {
1188
+ "state" => self.state,
1189
+ "range" => self.range,
1190
+ "stepSeconds" => self.step_seconds,
1191
+ "since" => self.since,
1192
+ "until" => self.until,
1193
+ "vcpu" => self.vcpu,
1194
+ "memoryLimitBytes" => self.memory_limit_bytes,
1195
+ "diskLimitBytes" => self.disk_limit_bytes,
1196
+ "latest" => self.latest&.to_wire,
1197
+ "points" => self.points&.map { |i| i&.to_wire },
1198
+ "id" => self.id,
1199
+ }.compact
1200
+ end
1201
+ end
1202
+
1203
+ # Copies of a sandbox to make, as it is now.
1204
+ # - +count+: How many. At least 1. At most 100. Default: 1.
1205
+ # - +name+: Its name, for a fork of one.
1206
+ # - +labels+: Labels each copy gets.
1207
+ # - +secrets+: The secrets each copy gets, by name: only these, never one its source may not use; its source's when omitted. At most 64 items.
1208
+ # - +max_cost+: The most each may cost in all, in US dollars (`"5.00"`): once one has cost that it pauses, as a create's maxCost. When omitted, the least of its key's caps and its source's maxCost.
1209
+ # - +idle_pause_seconds+: Seconds with nothing happening before each copy pauses, 60 to 86400; 0 never. When omitted, its source's, unless its source never pauses (0): then its product's default, 300 for a sandbox. At least 0. At most 86400.
1210
+ ForkRequest = Struct.new(:count, :name, :labels, :secrets, :max_cost, :idle_pause_seconds, keyword_init: true) do
1211
+ def self.from(h)
1212
+ return nil if h.nil?
1213
+
1214
+ new(
1215
+ count: h["count"],
1216
+ name: h["name"],
1217
+ labels: h["labels"],
1218
+ secrets: h["secrets"],
1219
+ max_cost: h["maxCost"],
1220
+ idle_pause_seconds: h["idlePauseSeconds"],
1221
+ )
1222
+ end
1223
+
1224
+ def to_wire
1225
+ {
1226
+ "count" => self.count,
1227
+ "name" => self.name,
1228
+ "labels" => self.labels,
1229
+ "secrets" => self.secrets,
1230
+ "maxCost" => self.max_cost,
1231
+ "idlePauseSeconds" => self.idle_pause_seconds,
1232
+ }.compact
1233
+ end
1234
+ end
1235
+
1236
+ # The copies a fork made, each running.
1237
+ # - +sandboxes+: The copies, in the order made.
1238
+ Forked = Struct.new(:sandboxes, keyword_init: true) do
1239
+ def self.from(h)
1240
+ return nil if h.nil?
1241
+
1242
+ new(
1243
+ sandboxes: h["sandboxes"]&.map { |i| Sandbox.from(i) },
1244
+ )
1245
+ end
1246
+
1247
+ def to_wire
1248
+ {
1249
+ "sandboxes" => self.sandboxes&.map { |i| i&.to_wire },
1250
+ }.compact
1251
+ end
1252
+ end
1253
+
1254
+ # A snapshot of a sandbox to take.
1255
+ # - +name+: Its name, unique among the project's snapshots.
1256
+ # - +labels+: Labels to find it by.
1257
+ # - +image+: Keeps its disk alone, synced, as the next version of the image of this name (`name:1`, `name:2`, ...) in place of a snapshot: an image machines are created from, each booting fresh over a disk of its own. Its memory is not kept; name is ignored.
1258
+ # - +start+: With image: the command each machine created from the image starts at every fresh boot; the sandbox's own when omitted.
1259
+ SnapshotRequest = Struct.new(:name, :labels, :image, :start, keyword_init: true) do
1260
+ def self.from(h)
1261
+ return nil if h.nil?
1262
+
1263
+ new(
1264
+ name: h["name"],
1265
+ labels: h["labels"],
1266
+ image: h["image"],
1267
+ start: MachineStart.from(h["start"]),
1268
+ )
1269
+ end
1270
+
1271
+ def to_wire
1272
+ {
1273
+ "name" => self.name,
1274
+ "labels" => self.labels,
1275
+ "image" => self.image,
1276
+ "start" => self.start&.to_wire,
1277
+ }.compact
1278
+ end
1279
+ end
1280
+
1281
+ # Stored data: a snapshot, an image or a volume.
1282
+ # - +id+: Its ID.
1283
+ # - +object+: Its kind: `snapshot`, `image` or `volume`.
1284
+ # - +name+: Its name, unique in its project among its kind.
1285
+ # - +state+: Where it is.
1286
+ # - +labels+: Its labels.
1287
+ # - +size_bytes+: What it was made to hold, in bytes.
1288
+ # - +stored_bytes+: What it holds now, in bytes.
1289
+ # - +parent_id+: What it was made from (a snapshot's sandbox, an image's base), if anything.
1290
+ # - +attached_to+: The machine it is attached to now, if any.
1291
+ # - +created_at+: When it was made.
1292
+ # - +version+: An image's version of its name: each build or keep of a name is its next.
1293
+ # - +tags+: An image's tags, each `name:tag`.
1294
+ # - +error+: Why an image's build failed.
1295
+ # - +deleted_at+: When it was deleted: a delete's answer, its state `deleted`.
1296
+ Stored = Struct.new(:id, :object, :name, :state, :labels, :size_bytes, :stored_bytes, :parent_id, :attached_to, :created_at, :version, :tags, :error, :deleted_at, keyword_init: true) do
1297
+ def self.from(h)
1298
+ return nil if h.nil?
1299
+
1300
+ new(
1301
+ id: h["id"],
1302
+ object: h["object"],
1303
+ name: h["name"],
1304
+ state: h["state"],
1305
+ labels: h["labels"],
1306
+ size_bytes: h["sizeBytes"],
1307
+ stored_bytes: h["storedBytes"],
1308
+ parent_id: h["parentId"],
1309
+ attached_to: h["attachedTo"],
1310
+ created_at: h["createdAt"],
1311
+ version: h["version"],
1312
+ tags: h["tags"],
1313
+ error: h["error"],
1314
+ deleted_at: h["deletedAt"],
1315
+ )
1316
+ end
1317
+
1318
+ def to_wire
1319
+ {
1320
+ "id" => self.id,
1321
+ "object" => self.object,
1322
+ "name" => self.name,
1323
+ "state" => self.state,
1324
+ "labels" => self.labels,
1325
+ "sizeBytes" => self.size_bytes,
1326
+ "storedBytes" => self.stored_bytes,
1327
+ "parentId" => self.parent_id,
1328
+ "attachedTo" => self.attached_to,
1329
+ "createdAt" => self.created_at,
1330
+ "version" => self.version,
1331
+ "tags" => self.tags,
1332
+ "error" => self.error,
1333
+ "deletedAt" => self.deleted_at,
1334
+ }.compact
1335
+ end
1336
+ end
1337
+
1338
+ # A change to a machine's settings: each field left out stays as it is.
1339
+ # - +name+: Its name, unique in its project.
1340
+ # - +labels+: Its labels, in place of its own; those under `runtime.` are kept.
1341
+ # - +idle_pause_seconds+: Seconds with nothing happening before it pauses, 60 to 86400; 0 never.
1342
+ # - +vcpu+: Its vCPUs, grown while it runs; a running sandbox's vCPUs only grow. At least 1.
1343
+ # - +memory_gb+: Its memory in GB (1 GB is 1,024 MiB), grown while it runs; a running sandbox's memory only grows. At least 1.
1344
+ # - +disk_gb+: Its disk in GB (1 GB is 1,024 MiB), grown while it runs, its file system with it; a disk only grows. At least 1.
1345
+ # - +user+: Who its commands run as from now when a call names no `user`: `runtime` or `root`. Running ones keep theirs.
1346
+ # - +env+: Environment variables to set, each over its own value, the others kept: the update answers once a running one holds the change (a paused one is given it at its wake), so each process, command and terminal it starts after the answer has them; processes already running keep the environment they started with. At most 32 variables and 32768 bytes of names and values in all, as a create's; values are never answered.
1347
+ # - +remove_env+: Names of environment variables to take out, the same way: gone from the next process it starts; processes already running keep them.
1348
+ # - +max_cost+: The most it may cost in all, in US dollars (`"5.00"`), in place of its own: one paused at its old maxCost wakes at its next call under a higher one.
1349
+ MachineUpdate = Struct.new(:name, :labels, :idle_pause_seconds, :vcpu, :memory_gb, :disk_gb, :user, :env, :remove_env, :max_cost, keyword_init: true) do
1350
+ def self.from(h)
1351
+ return nil if h.nil?
1352
+
1353
+ new(
1354
+ name: h["name"],
1355
+ labels: h["labels"],
1356
+ idle_pause_seconds: h["idlePauseSeconds"],
1357
+ vcpu: h["vcpu"],
1358
+ memory_gb: h["memoryGB"],
1359
+ disk_gb: h["diskGB"],
1360
+ user: h["user"],
1361
+ env: h["env"],
1362
+ remove_env: h["removeEnv"],
1363
+ max_cost: h["maxCost"],
1364
+ )
1365
+ end
1366
+
1367
+ def to_wire
1368
+ {
1369
+ "name" => self.name,
1370
+ "labels" => self.labels,
1371
+ "idlePauseSeconds" => self.idle_pause_seconds,
1372
+ "vcpu" => self.vcpu,
1373
+ "memoryGB" => self.memory_gb,
1374
+ "diskGB" => self.disk_gb,
1375
+ "user" => self.user,
1376
+ "env" => self.env,
1377
+ "removeEnv" => self.remove_env,
1378
+ "maxCost" => self.max_cost,
1379
+ }.compact
1380
+ end
1381
+ end
1382
+
1383
+ # One step of an act: a mouse move, click, drag or scroll, typed text, a key chord, or a wait.
1384
+ # - +type+: What it does: `move` to `x`,`y`; `click` (at `x`,`y` when given, `count` times, with `keys` held); `mouseDown` and `mouseUp` of `button`; `drag` from `x`,`y` to `toX`,`toY`; `scroll` by `dx`,`dy` wheel clicks (at `x`,`y` when given); `type` `text`; `key` the chords in `keys`; `wait` `ms`.
1385
+ # - +x+: Pixels from the screen's left edge. At least 0. At most 16384.
1386
+ # - +y+: Pixels from the screen's top edge. At least 0. At most 16384.
1387
+ # - +to_x+: A drag's end, from the left edge. At least 0. At most 16384.
1388
+ # - +to_y+: A drag's end, from the top edge. At least 0. At most 16384.
1389
+ # - +button+: The mouse button of a click, a drag, a mouseDown or a mouseUp. Default: "left".
1390
+ # - +count+: A click's count: 2 a double click, 3 a triple click. At least 1. At most 3. Default: 1.
1391
+ # - +dx+: A scroll's wheel clicks to the right (negative to the left). At least -100. At most 100.
1392
+ # - +dy+: A scroll's wheel clicks down (negative up). At least -100. At most 100.
1393
+ # - +text+: The text a `type` types, as it is: any Unicode, newlines and tabs. At most 8192 characters.
1394
+ # - +keys+: For `key`, chords pressed in turn, space-separated, each keys joined by `+` in X keysym names (`ctrl+l`, `Return`, `ctrl+shift+t`); for `click` and `scroll`, the modifiers held during it (`shift`, `ctrl+alt`). At most 1000 characters.
1395
+ # - +ms+: A wait's milliseconds. At least 0. At most 10000.
1396
+ Action = Struct.new(:type, :x, :y, :to_x, :to_y, :button, :count, :dx, :dy, :text, :keys, :ms, keyword_init: true) do
1397
+ def self.from(h)
1398
+ return nil if h.nil?
1399
+
1400
+ new(
1401
+ type: h["type"],
1402
+ x: h["x"],
1403
+ y: h["y"],
1404
+ to_x: h["toX"],
1405
+ to_y: h["toY"],
1406
+ button: h["button"],
1407
+ count: h["count"],
1408
+ dx: h["dx"],
1409
+ dy: h["dy"],
1410
+ text: h["text"],
1411
+ keys: h["keys"],
1412
+ ms: h["ms"],
1413
+ )
1414
+ end
1415
+
1416
+ def to_wire
1417
+ {
1418
+ "type" => self.type,
1419
+ "x" => self.x,
1420
+ "y" => self.y,
1421
+ "toX" => self.to_x,
1422
+ "toY" => self.to_y,
1423
+ "button" => self.button,
1424
+ "count" => self.count,
1425
+ "dx" => self.dx,
1426
+ "dy" => self.dy,
1427
+ "text" => self.text,
1428
+ "keys" => self.keys,
1429
+ "ms" => self.ms,
1430
+ }.compact
1431
+ end
1432
+ end
1433
+
1434
+ # Steps of the mouse and keyboard, run in order as one command.
1435
+ # - +actions+: The steps, in order; the act stops at the first that fails. At least 1 item. At most 100 items.
1436
+ ActRequest = Struct.new(:actions, keyword_init: true) do
1437
+ def self.from(h)
1438
+ return nil if h.nil?
1439
+
1440
+ new(
1441
+ actions: h["actions"]&.map { |i| Action.from(i) },
1442
+ )
1443
+ end
1444
+
1445
+ def to_wire
1446
+ {
1447
+ "actions" => self.actions&.map { |i| i&.to_wire },
1448
+ }.compact
1449
+ end
1450
+ end
1451
+
1452
+ # A point on the screen, in pixels from its top left corner.
1453
+ # - +x+:
1454
+ # - +y+:
1455
+ Point = Struct.new(:x, :y, keyword_init: true) do
1456
+ def self.from(h)
1457
+ return nil if h.nil?
1458
+
1459
+ new(
1460
+ x: h["x"],
1461
+ y: h["y"],
1462
+ )
1463
+ end
1464
+
1465
+ def to_wire
1466
+ {
1467
+ "x" => self.x,
1468
+ "y" => self.y,
1469
+ }.compact
1470
+ end
1471
+ end
1472
+
1473
+ # The screen's size, in pixels.
1474
+ # - +width+:
1475
+ # - +height+:
1476
+ ScreenSize = Struct.new(:width, :height, keyword_init: true) do
1477
+ def self.from(h)
1478
+ return nil if h.nil?
1479
+
1480
+ new(
1481
+ width: h["width"],
1482
+ height: h["height"],
1483
+ )
1484
+ end
1485
+
1486
+ def to_wire
1487
+ {
1488
+ "width" => self.width,
1489
+ "height" => self.height,
1490
+ }.compact
1491
+ end
1492
+ end
1493
+
1494
+ # The screen once an act's steps ran.
1495
+ # - +cursor+: Where the mouse is.
1496
+ # - +screen+: The screen's size.
1497
+ Acted = Struct.new(:cursor, :screen, keyword_init: true) do
1498
+ def self.from(h)
1499
+ return nil if h.nil?
1500
+
1501
+ new(
1502
+ cursor: Point.from(h["cursor"]),
1503
+ screen: ScreenSize.from(h["screen"]),
1504
+ )
1505
+ end
1506
+
1507
+ def to_wire
1508
+ {
1509
+ "cursor" => self.cursor&.to_wire,
1510
+ "screen" => self.screen&.to_wire,
1511
+ }.compact
1512
+ end
1513
+ end
1514
+
1515
+ # A cell to run.
1516
+ # - +code+: The code. At most 1048576 characters.
1517
+ # - +language+: Its language: `python`. Default: "python".
1518
+ # - +context+: The context it runs in, each its own kernel and state, started on its first cell (`a-z`, `0-9`, `-`, at most 63); `default` when omitted. At least 1 character. At most 63 characters.
1519
+ # - +timeout_seconds+: Seconds it may run before it is interrupted, its context kept: 1 to 50, 45 when omitted. Run longer work as a process (exec with `wait: false`). At least 1. At most 50.
1520
+ RunCode = Struct.new(:code, :language, :context, :timeout_seconds, keyword_init: true) do
1521
+ def self.from(h)
1522
+ return nil if h.nil?
1523
+
1524
+ new(
1525
+ code: h["code"],
1526
+ language: h["language"],
1527
+ context: h["context"],
1528
+ timeout_seconds: h["timeoutSeconds"],
1529
+ )
1530
+ end
1531
+
1532
+ def to_wire
1533
+ {
1534
+ "code" => self.code,
1535
+ "language" => self.language,
1536
+ "context" => self.context,
1537
+ "timeoutSeconds" => self.timeout_seconds,
1538
+ }.compact
1539
+ end
1540
+ end
1541
+
1542
+ # One value a cell returned or displayed, in each form it gave.
1543
+ # - +main+: The cell's own value (its last expression), rather than a display.
1544
+ # - +text+: As plain text (`text/plain`).
1545
+ # - +html+: As HTML (`text/html`): a table, for a DataFrame.
1546
+ # - +markdown+: As Markdown (`text/markdown`).
1547
+ # - +json+: As JSON text (`application/json`).
1548
+ # - +png+: As a PNG image (`image/png`): a chart.
1549
+ # - +jpeg+: As a JPEG image (`image/jpeg`).
1550
+ # - +svg+: As an SVG image (`image/svg+xml`).
1551
+ # - +latex+: As LaTeX (`text/latex`).
1552
+ CodeResult = Struct.new(:main, :text, :html, :markdown, :json, :png, :jpeg, :svg, :latex, keyword_init: true) do
1553
+ def self.from(h)
1554
+ return nil if h.nil?
1555
+
1556
+ new(
1557
+ main: h["main"],
1558
+ text: h["text"],
1559
+ html: h["html"],
1560
+ markdown: h["markdown"],
1561
+ json: h["json"],
1562
+ png: h["png"],
1563
+ jpeg: h["jpeg"],
1564
+ svg: h["svg"],
1565
+ latex: h["latex"],
1566
+ )
1567
+ end
1568
+
1569
+ def to_wire
1570
+ {
1571
+ "main" => self.main,
1572
+ "text" => self.text,
1573
+ "html" => self.html,
1574
+ "markdown" => self.markdown,
1575
+ "json" => self.json,
1576
+ "png" => self.png,
1577
+ "jpeg" => self.jpeg,
1578
+ "svg" => self.svg,
1579
+ "latex" => self.latex,
1580
+ }.compact
1581
+ end
1582
+ end
1583
+
1584
+ # The exception a cell raised.
1585
+ # - +name+: Its name (`ZeroDivisionError`).
1586
+ # - +value+: Its message.
1587
+ # - +traceback+: Its traceback, as text.
1588
+ CodeError = Struct.new(:name, :value, :traceback, keyword_init: true) do
1589
+ def self.from(h)
1590
+ return nil if h.nil?
1591
+
1592
+ new(
1593
+ name: h["name"],
1594
+ value: h["value"],
1595
+ traceback: h["traceback"],
1596
+ )
1597
+ end
1598
+
1599
+ def to_wire
1600
+ {
1601
+ "name" => self.name,
1602
+ "value" => self.value,
1603
+ "traceback" => self.traceback,
1604
+ }.compact
1605
+ end
1606
+ end
1607
+
1608
+ # A cell that ran.
1609
+ # - +context+: The context it ran in.
1610
+ # - +language+: Its language.
1611
+ # - +status+: `ok`; `error`, an exception (`error`); `timeout`, interrupted at its time, its context kept.
1612
+ # - +execution_count+: Its number in its context, as a notebook counts cells.
1613
+ # - +stdout+: What it printed.
1614
+ # - +stderr+: What it wrote to standard error.
1615
+ # - +results+: The values it returned and displayed, in order.
1616
+ # - +error+: The exception it raised.
1617
+ # - +started+: Whether its context's kernel was started for it: its first cell, or one after the kernel ended.
1618
+ # - +duration_seconds+: How long it ran, in seconds.
1619
+ CodeRun = Struct.new(:context, :language, :status, :execution_count, :stdout, :stderr, :results, :error, :started, :duration_seconds, keyword_init: true) do
1620
+ def self.from(h)
1621
+ return nil if h.nil?
1622
+
1623
+ new(
1624
+ context: h["context"],
1625
+ language: h["language"],
1626
+ status: h["status"],
1627
+ execution_count: h["executionCount"],
1628
+ stdout: h["stdout"],
1629
+ stderr: h["stderr"],
1630
+ results: h["results"]&.map { |i| CodeResult.from(i) },
1631
+ error: CodeError.from(h["error"]),
1632
+ started: h["started"],
1633
+ duration_seconds: h["durationSeconds"],
1634
+ )
1635
+ end
1636
+
1637
+ def to_wire
1638
+ {
1639
+ "context" => self.context,
1640
+ "language" => self.language,
1641
+ "status" => self.status,
1642
+ "executionCount" => self.execution_count,
1643
+ "stdout" => self.stdout,
1644
+ "stderr" => self.stderr,
1645
+ "results" => self.results&.map { |i| i&.to_wire },
1646
+ "error" => self.error&.to_wire,
1647
+ "started" => self.started,
1648
+ "durationSeconds" => self.duration_seconds,
1649
+ }.compact
1650
+ end
1651
+ end
1652
+
1653
+ # A Linux machine with its own kernel, made in milliseconds, paused with its memory kept when idle and resumed where it was. Its life: running, then idle, then paused, until you delete it. A paused sandbox is kept with its memory and disk until it is deleted: it has no time limit, no retention period and no expiry, and nothing deletes it for its age. Every 30 days a sandbox stays paused with nothing changing it, a `sandbox.still_paused` event is written for its organization.
1654
+ class Sandboxes
1655
+ def initialize(transport)
1656
+ @transport = transport
1657
+ end
1658
+
1659
+ # Creates a sandbox. Asked again with the same Idempotency-Key, it returns the same sandbox.
1660
+ def create(vcpu: nil, memory_gb: nil, disk_gb: nil, image: nil, secrets: nil, start: nil, user: nil, volumes: nil, run: nil, name: nil, labels: nil, get_or_create: nil, max_cost: nil, idle_pause_seconds: nil, snapshot: nil, network: nil, env: nil, idempotency_key: nil)
1661
+ Sandbox.from(@transport.request("POST", "/v2/sandboxes", body: { "vcpu" => vcpu, "memoryGB" => memory_gb, "diskGB" => disk_gb, "image" => image, "secrets" => secrets, "start" => start, "user" => user, "volumes" => volumes, "run" => run, "name" => name, "labels" => labels, "getOrCreate" => get_or_create, "maxCost" => max_cost, "idlePauseSeconds" => idle_pause_seconds, "snapshot" => snapshot, "network" => network, "env" => env }.compact, idempotency_key: idempotency_key, idempotent: true))
1662
+ end
1663
+
1664
+ # Returns a sandbox.
1665
+ def get(id, wait: nil, if_state: nil)
1666
+ Sandbox.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}", query: { "wait" => wait, "ifState" => if_state }, idempotent: true))
1667
+ end
1668
+
1669
+ # Lists the project's sandboxes, newest first.
1670
+ def list(state: nil, name: nil, label: nil, cursor: nil, limit: nil)
1671
+ Generated.page(@transport.request("GET", "/v2/sandboxes", query: { "state" => state, "name" => name, "label" => label, "cursor" => cursor, "limit" => limit }, idempotent: true)) { |i| Sandbox.from(i) }
1672
+ end
1673
+
1674
+ # Deletes a sandbox, its memory and its disk.
1675
+ def delete(id, idempotency_key: nil)
1676
+ Sandbox.from(@transport.request("DELETE", "/v2/sandboxes/#{URI.encode_www_form_component(id)}", idempotency_key: idempotency_key))
1677
+ end
1678
+
1679
+ # Pauses a sandbox with its memory and disk kept. A call to it resumes it.
1680
+ def pause(id, idempotency_key: nil)
1681
+ Sandbox.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:pause", idempotency_key: idempotency_key))
1682
+ end
1683
+
1684
+ # Resumes a paused sandbox where it was, its memory and processes as they were.
1685
+ def resume(id, idempotency_key: nil)
1686
+ Sandbox.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:resume", idempotency_key: idempotency_key))
1687
+ end
1688
+
1689
+ # Runs a command as a process and returns it once it ended, with its output; with wait false, at once, while it runs. A paused sandbox is resumed first. Asked again with the same Idempotency-Key, it runs nothing more: it returns the first run's process, waiting for its end while it runs.
1690
+ def exec(id, cmd:, cwd: nil, env: nil, stdin: nil, timeout_seconds: nil, stream: nil, wait: nil, stdin_open: nil, output_encoding: nil, pty: nil, user: nil, idempotency_key: nil)
1691
+ Process.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:exec", body: { "cmd" => cmd, "cwd" => cwd, "env" => env, "stdin" => stdin, "timeoutSeconds" => timeout_seconds, "stream" => stream, "wait" => wait, "stdinOpen" => stdin_open, "outputEncoding" => output_encoding, "pty" => pty, "user" => user }.compact, idempotency_key: idempotency_key, idempotent: true, runs: true, runs_seconds: timeout_seconds))
1692
+ end
1693
+
1694
+ # Returns a file's bytes.
1695
+ def read(id, path:)
1696
+ @transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files", query: { "path" => path }, raw: true, idempotent: true)
1697
+ end
1698
+
1699
+ # Writes the request's bytes to a file as they come, of any size (Content-Length required), its folders made: the file whole when they all came, or as it was. With offset, they are written into it in place.
1700
+ def write(id, data, path:, mode: nil, offset: nil, sha256: nil, idempotency_key: nil)
1701
+ FileWritten.from(@transport.request("PUT", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files", query: { "path" => path, "mode" => mode, "offset" => offset, "sha256" => sha256 }, data: data, idempotency_key: idempotency_key))
1702
+ end
1703
+
1704
+ # Returns a process's output after a cursor, and the cursor to read on from. The latest 1 MiB is kept; truncated says when the cursor fell behind.
1705
+ def process_output(id, process, cursor: nil, wait_seconds: nil, max_bytes: nil, follow: nil)
1706
+ ProcessOutput.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/processes/#{URI.encode_www_form_component(process)}/output", query: { "cursor" => cursor, "waitSeconds" => wait_seconds, "maxBytes" => max_bytes, "follow" => follow }, idempotent: true))
1707
+ end
1708
+
1709
+ # Sends input to a process started with stdinOpen or a pty, and returns how much of its input it has taken.
1710
+ def write_process(id, process, data: nil, offset: nil, eof: nil, idempotency_key: nil)
1711
+ ProcessWritten.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/processes/#{URI.encode_www_form_component(process)}:write", body: { "data" => data, "offset" => offset, "eof" => eof }.compact, idempotency_key: idempotency_key))
1712
+ end
1713
+
1714
+ # Sends a signal to a process and its group; a process that ended is not signalled, so a retry is safe.
1715
+ def signal_process(id, process, signal: nil, idempotency_key: nil)
1716
+ Process.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/processes/#{URI.encode_www_form_component(process)}:signal", body: { "signal" => signal }.compact, idempotency_key: idempotency_key, idempotent: true))
1717
+ end
1718
+
1719
+ # Lists a sandbox's processes, newest first: those running and those that ended lately.
1720
+ def list_processes(id)
1721
+ ProcessList.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/processes", idempotent: true))
1722
+ end
1723
+
1724
+ # Removes a file, a link or a directory (recursive for one with contents). One missing is success, removed false.
1725
+ def remove(id, path:, recursive: nil, idempotency_key: nil)
1726
+ FileRemoved.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files:remove", body: { "path" => path, "recursive" => recursive }.compact, idempotency_key: idempotency_key))
1727
+ end
1728
+
1729
+ # Returns what is at a path: a file, a directory or a link, or nothing (exists false). With sha256=true, a file's SHA-256 too.
1730
+ def stat(id, path:, sha256: nil)
1731
+ FileInfo.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/stat", query: { "path" => path, "sha256" => sha256 }, idempotent: true))
1732
+ end
1733
+
1734
+ # Lists a directory's entries in path order, to a depth.
1735
+ def list_files(id, path: nil, depth: nil, limit: nil, hidden: nil, glob: nil)
1736
+ FileList.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/list", query: { "path" => path, "depth" => depth, "limit" => limit, "hidden" => hidden, "glob" => glob }, idempotent: true))
1737
+ end
1738
+
1739
+ # Returns a folder as a tar archive (`application/x-tar`, or `application/gzip` with gzip), packed by tar in the sandbox as it streams, of any size; its entries are relative to the folder (`./a.txt`). A folder that fails part way (a file it may not read, or one that changes as it is read) ends as an archive every tar reader refuses, never as a short one that reads whole. At most 4 at once in a sandbox. A paused sandbox is woken first.
1740
+ def download_folder(id, path:, gzip: nil, user: nil, exclude: nil)
1741
+ @transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/archive", query: { "path" => path, "gzip" => gzip, "user" => user, "exclude" => exclude }, raw: true, idempotent: true)
1742
+ end
1743
+
1744
+ # Unpacks the request's tar archive (gzip-compressed or not, told by its first bytes) into a folder, made with its parents, by tar in the sandbox as the bytes arrive, of any size, nothing of it kept on disk but what tar writes; returns once tar has ended, or 400 `invalid_archive` with what tar said. A paused sandbox is woken first.
1745
+ def upload_folder(id, data, path:, user: nil, idempotency_key: nil)
1746
+ FolderUnpacked.from(@transport.request("PUT", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/archive", query: { "path" => path, "user" => user }, data: data, idempotency_key: idempotency_key, idempotent: true))
1747
+ end
1748
+
1749
+ # Begins a folder's upload in parts: tar starts in the sandbox, unpacking into the folder each part as it arrives. Send the parts in order by offset (writeFolderUpload), then commitFolderUpload; an upload no call names for 10 minutes is ended. A paused sandbox is woken first.
1750
+ def begin_folder_upload(id, path:, gzip: nil, user: nil, idempotency_key: nil)
1751
+ FolderUpload.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/archive/uploads", body: { "path" => path, "gzip" => gzip, "user" => user }.compact, idempotency_key: idempotency_key))
1752
+ end
1753
+
1754
+ # Sends the request's bytes, a part of the archive at its offset, into tar's input as they arrive, of any size, and returns the bytes received in all once tar took them. A part past them is refused 409 `upload_incomplete`, naming them: send the parts in order.
1755
+ def write_folder_upload(id, upload, data, offset: nil, idempotency_key: nil)
1756
+ FolderUploadReceived.from(@transport.request("PUT", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/archive/uploads/#{URI.encode_www_form_component(upload)}", query: { "offset" => offset }, data: data, idempotency_key: idempotency_key, idempotent: true))
1757
+ end
1758
+
1759
+ # Ends a folder upload's input and returns once tar has ended, as an exec returns once its command has: the folder, or 400 `invalid_archive` with what tar said. A front that restarts meanwhile returns 503 `run_goes_on`; sent again, it returns how tar ended. An upload no call has named for 10 minutes since its last part or commit is ended.
1760
+ def commit_folder_upload(id, upload, idempotency_key: nil)
1761
+ FolderUnpacked.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/archive/uploads/#{URI.encode_www_form_component(upload)}:commit", idempotency_key: idempotency_key, idempotent: true))
1762
+ end
1763
+
1764
+ # Stops a folder upload's tar; what it unpacked so far stays.
1765
+ def abort_folder_upload(id, upload, idempotency_key: nil)
1766
+ FolderUploadAborted.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files/archive/uploads/#{URI.encode_www_form_component(upload)}:abort", idempotency_key: idempotency_key, idempotent: true))
1767
+ end
1768
+
1769
+ # Makes a directory, and its parents unless parents is false. One there already is success, created false.
1770
+ def mkdir(id, path:, parents: nil, idempotency_key: nil)
1771
+ FileMade.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files:mkdir", body: { "path" => path, "parents" => parents }.compact, idempotency_key: idempotency_key, idempotent: true))
1772
+ end
1773
+
1774
+ # Moves a file, a link or a directory; refused 409 when something is at its new path, unless overwrite. With sha256 or size, a file written in parts is put in place once whole: its writes ended, then only a file of that size with every byte written and whose bytes hash to it moves; refused 409 `upload_incomplete` or `checksum_mismatch`, nothing moved. With sha256, it is safe to send again: once moved, it returns the same answer while `from` is gone and `to` holds those bytes.
1775
+ def rename(id, from:, to:, overwrite: nil, sha256: nil, size: nil, idempotency_key: nil)
1776
+ FileRenamed.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files:rename", body: { "from" => from, "to" => to, "overwrite" => overwrite, "sha256" => sha256, "size" => size }.compact, idempotency_key: idempotency_key))
1777
+ end
1778
+
1779
+ # Makes an expiring address for one file that anyone may open with no API key, from a browser, curl or another service: GET downloads it (Range works, so videos play and downloads resume; archive: true downloads a folder as .tar.gz), PUT with the raw body uploads it (up to maxBytes, written whole; Content-Length required). The link acts as the key that made it: an upload link needs write, and the link ends with its key, with revokeLinks or with its sandbox. A paused sandbox is woken for it unless wake is false.
1780
+ def link(id, path:, method: nil, expires_in_seconds: nil, filename: nil, max_bytes: nil, wake: nil, archive: nil, idempotency_key: nil)
1781
+ FileLink.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files:link", body: { "path" => path, "method" => method, "expiresInSeconds" => expires_in_seconds, "filename" => filename, "maxBytes" => max_bytes, "wake" => wake, "archive" => archive }.compact, idempotency_key: idempotency_key))
1782
+ end
1783
+
1784
+ # Ends every file link made for a sandbox so far; links made after work.
1785
+ def revoke_links(id, idempotency_key: nil)
1786
+ FileLinksRevoked.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/files:revokeLinks", idempotency_key: idempotency_key))
1787
+ end
1788
+
1789
+ # Returns where a sandbox may connect out.
1790
+ def get_network(id)
1791
+ SandboxNetwork.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/network", idempotent: true))
1792
+ end
1793
+
1794
+ # Returns a sandbox's CPU, memory, disks and pressure, as its host reads them from the sandbox's own cgroup over a fifth of a second: never a call into the sandbox, so it does not wake a paused one nor keep one from its idle pause. One that is not running has no reading.
1795
+ def metrics(id, range: nil)
1796
+ SandboxMetrics.from(@transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/metrics", query: { "range" => range }, idempotent: true))
1797
+ end
1798
+
1799
+ # Replaces where a sandbox may connect out, for its next connection and within a second for its open ones: those the new rules refuse are cut.
1800
+ def set_network(id, allow_outbound: nil, deny_outbound: nil, idempotency_key: nil)
1801
+ SandboxNetwork.from(@transport.request("PUT", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/network", body: { "allowOutbound" => allow_outbound, "denyOutbound" => deny_outbound }.compact, idempotency_key: idempotency_key))
1802
+ end
1803
+
1804
+ # Copies a sandbox as it is now, memory and disk, into `count` copies of its own, each running on its host. Asked again with the same Idempotency-Key, it returns the same copies.
1805
+ def fork(id, count: nil, name: nil, labels: nil, secrets: nil, max_cost: nil, idle_pause_seconds: nil, idempotency_key: nil)
1806
+ Forked.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:fork", body: { "count" => count, "name" => name, "labels" => labels, "secrets" => secrets, "maxCost" => max_cost, "idlePauseSeconds" => idle_pause_seconds }.compact, idempotency_key: idempotency_key, idempotent: true))
1807
+ end
1808
+
1809
+ # Keeps a sandbox's memory and disk as they are now, a snapshot to start sandboxes from; with `image`, its disk alone as that image's next version. The sandbox runs on. Asked again with the same Idempotency-Key, it returns the same snapshot.
1810
+ def snapshot(id, name: nil, labels: nil, image: nil, start: nil, idempotency_key: nil)
1811
+ Stored.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:snapshot", body: { "name" => name, "labels" => labels, "image" => image, "start" => start }.compact, idempotency_key: idempotency_key, idempotent: true))
1812
+ end
1813
+
1814
+ # Changes its name, labels, idle pause, maxCost, environment or sizes; each field left out stays as it is. A running one holds a changed environment before this answers (a paused one's at its wake): each process it starts after the answer has it, and its running processes keep the one they started with. Its vCPUs, memory and disk grow while it runs, its commands running on; a smaller size, or a sandbox that is not running, is refused 409 naming why, and nothing is changed. With If-Match, made only while its revision is that one, else 412.
1815
+ def update(id, name: nil, labels: nil, idle_pause_seconds: nil, vcpu: nil, memory_gb: nil, disk_gb: nil, user: nil, env: nil, remove_env: nil, max_cost: nil, idempotency_key: nil)
1816
+ Sandbox.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:update", body: { "name" => name, "labels" => labels, "idlePauseSeconds" => idle_pause_seconds, "vcpu" => vcpu, "memoryGB" => memory_gb, "diskGB" => disk_gb, "user" => user, "env" => env, "removeEnv" => remove_env, "maxCost" => max_cost }.compact, idempotency_key: idempotency_key))
1817
+ end
1818
+
1819
+ # Returns what a sandbox's screen shows now, as `image/png` (or `image/jpeg`): its X display `:1`, whole. Refused 409 `display_not_running` when no display runs. A paused sandbox is resumed first.
1820
+ def screenshot(id, format: nil, quality: nil)
1821
+ @transport.request("GET", "/v2/sandboxes/#{URI.encode_www_form_component(id)}/screenshot", query: { "format" => format, "quality" => quality }, raw: true, idempotent: true)
1822
+ end
1823
+
1824
+ # Moves, clicks, drags and scrolls the mouse and types on the keyboard of a sandbox's screen (its X display `:1`), each step in turn as one command, and returns where the mouse is then. It stops at the first step that fails, refused 409 `act_failed` naming it; refused 409 `display_not_running` when no display runs. A paused sandbox is resumed first.
1825
+ def act(id, actions:, idempotency_key: nil)
1826
+ Acted.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:act", body: { "actions" => actions }.compact, idempotency_key: idempotency_key))
1827
+ end
1828
+
1829
+ # Runs a cell of Python in a sandbox as a notebook does, in a Jupyter kernel it keeps running for the cell's `context`: variables, imports and functions stay for the next cell. Returns what it printed, its values and displays (text, HTML, images such as charts), and its exception with its traceback. The context's kernel starts on its first cell. A cell past `timeoutSeconds` is interrupted and its context kept. Refused 409 `kernel_not_installed` when the image has no ipykernel. A paused sandbox is resumed first.
1830
+ def run_code(id, code:, language: nil, context: nil, timeout_seconds: nil, idempotency_key: nil)
1831
+ CodeRun.from(@transport.request("POST", "/v2/sandboxes/#{URI.encode_www_form_component(id)}:runCode", body: { "code" => code, "language" => language, "context" => context, "timeoutSeconds" => timeout_seconds }.compact, idempotency_key: idempotency_key))
1832
+ end
1833
+ end
1834
+ end
1835
+ end