withruntime 0.27.1 → 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 -770
  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
@@ -1,770 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require "digest"
4
- require "fileutils"
5
- require "securerandom"
6
- require "time"
7
-
8
- module WithRuntime
9
- # +runtime.sandboxes+: create, find and list sandboxes.
10
- class Sandboxes
11
- def initialize(transport)
12
- @t = transport
13
- end
14
-
15
- # Creates a sandbox and, unless +wait: false+, waits until it is running.
16
- # Every field is optional: with none you get the free usage while it lasts,
17
- # the default region and a 2 vCPU / 4 GiB machine for up to 30 minutes.
18
- # When every slot without credit or the account's quota is taken, it waits for one to
19
- # free, up to +wait_for_capacity+ seconds (the client's, two minutes by default).
20
- #
21
- # runtime.sandboxes.create(labels: { team: "search" }, timeout_seconds: 900)
22
- #
23
- # +spread_from: [id, ...]+ (one to 16 ids of your own sandboxes or snapshots)
24
- # starts it on a server none of them is on. With no other server that has
25
- # room, the create raises +no_capacity+ and nothing is made or charged.
26
- # +sbx.info.placement+ is an opaque tag for its server: the same tag means
27
- # the same server.
28
- #
29
- # +secrets: [name, ...]+ is the egress secrets this sandbox may use, by
30
- # name: only those of your egress secrets that would otherwise reach it.
31
- # +[]+ is none; leave it out for every secret that reaches it. Fixed for
32
- # the sandbox's life; a copy of a snapshot may only narrow its source's
33
- # list. +sbx.info.secrets+ reads it back, nil for every secret.
34
- def create(wait: true, idempotency_key: nil, wait_for_capacity: nil, **fields)
35
- room = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
36
- info = @t.json("POST", "/v1/sandboxes", body: Fields.body(fields), wait: wait ? 60 : 0,
37
- key: idempotency_key, room: room)
38
- sandbox = Sandbox.new(@t, info)
39
- if wait && sandbox.state != "running"
40
- sandbox.wait_for("running", timeout: ApiDefaults::WAIT_FOR_TIMEOUT_SECONDS)
41
- unless sandbox.state == "running"
42
- message = if info["replayed"]
43
- "Sandbox #{sandbox.id} was made by an earlier call with this idempotency key and is #{sandbox.state} now. " \
44
- "It did not fail to start; create again with a new key."
45
- else
46
- "Sandbox #{sandbox.id} is #{sandbox.state}, not running."
47
- end
48
- raise Error.new(message, code: "start_failed",
49
- hint: "Read it with runtime.sandboxes.get(id); stop_reason says why.")
50
- end
51
- end
52
- sandbox
53
- end
54
-
55
- # The sandbox named +name+, ready to use: running as it is, woken if paused,
56
- # restarted if stopped and persistent, or created with the other fields when
57
- # no sandbox has the name. +sbx.info.reused+ says which.
58
- def get_or_create(name, **fields) = create(**fields, name: name, get_or_create: true)
59
-
60
- # Reconnects to a sandbox by id.
61
- def get(id) = Sandbox.new(@t, @t.json("GET", "/v1/sandboxes/#{Transport.segment(id)}"))
62
-
63
- # The first page of live sandboxes, oldest first; +each+ walks every page.
64
- def list(state: nil, include_stopped: false, labels: nil, name: nil, limit: nil)
65
- query = { "state" => state, "includeStopped" => (include_stopped ? "true" : nil),
66
- "label" => labels&.map { |key, value| "#{key}:#{value}" }, "name" => name, "limit" => limit }
67
- page(query, nil)
68
- end
69
-
70
- private
71
-
72
- def page(query, cursor)
73
- body = @t.json("GET", "/v1/sandboxes", query: query.merge("cursor" => cursor))
74
- Page.new(body["data"].map { |info| Sandbox.new(@t, info) }, body["nextCursor"]) { |after| page(query, after) }
75
- end
76
- end
77
-
78
- # A running (or stopped) sandbox. Its methods are safe to call from many threads.
79
- class Sandbox
80
- attr_reader :files, :previews, :network, :interpreter, :desktop, :info
81
-
82
- def initialize(transport, info)
83
- @t = transport
84
- @info = Record.new(info)
85
- @files = Files.new(self)
86
- @previews = Previews.new(self)
87
- @network = Network.new(self)
88
- @interpreter = Interpreter.new(self)
89
- @desktop = Desktop.new(self)
90
- @keep_alive = nil
91
- end
92
-
93
- # :nodoc:
94
- def transport = @t
95
- def mounts = Mounts.new(self)
96
- def mcp = SandboxMCP.new(self)
97
- def terminal(**options) = Terminal.new(self, **options)
98
- def open_tunnel = Tunnel.new(self)
99
- def port_forward(port, host: "127.0.0.1", local_port: 0) = PortForward.new(self, port, host: host, local_port: local_port)
100
-
101
- def id = @info["id"]
102
- def state = @info["state"]
103
-
104
- # :nodoc:
105
- def path(suffix = "") = "/v1/sandboxes/#{Transport.segment(id)}#{suffix}"
106
-
107
- # Reads the sandbox again.
108
- def refresh
109
- @info = Record.new(@t.json("GET", path))
110
- self
111
- end
112
-
113
- # Waits, on the server with no polling, until the sandbox reaches +state+
114
- # (running, paused or stopped) or +timeout+ seconds pass.
115
- def wait_for(state, timeout: ApiDefaults::WAIT_FOR_TIMEOUT_SECONDS)
116
- seconds = [1, timeout.to_i].max
117
- @info = Record.new(@t.json("GET", path, query: { "waitFor" => state, "timeoutSeconds" => seconds },
118
- timeout: seconds + 60))
119
- self
120
- end
121
-
122
- # Stops the sandbox and ends its charges. Also ends a keep-alive.
123
- def stop(wait: true, idempotency_key: nil)
124
- stop_keep_alive
125
- lifecycle("stop", {}, wait, idempotency_key)
126
- end
127
-
128
- # Saves the sandbox's memory and files; compute billing stops.
129
- def pause(wait: true, idempotency_key: nil) = lifecycle("pause", {}, wait, idempotency_key)
130
-
131
- # Carries on a paused sandbox, with its memory and processes;
132
- # +timeout_seconds+ is its new time limit, for a sandbox that has one.
133
- # When its server has no room (+no_capacity+) it waits for room, as +create+
134
- # does, up to +wait_for_capacity+ seconds (the client's, two minutes by
135
- # default; 0 fails at once), sending the same idempotency key each time.
136
- def wake(wait: true, timeout_seconds: nil, idempotency_key: nil, wait_for_capacity: nil)
137
- lifecycle("wake", timeout_seconds ? { "timeoutSeconds" => timeout_seconds } : {}, wait, idempotency_key,
138
- room: room_for(wait_for_capacity))
139
- end
140
-
141
- # Moves a sandbox's time limit on, at most an hour ahead of now. A sandbox
142
- # with no time limit answers at once and nothing changes.
143
- def extend_lease(seconds, idempotency_key: nil) = lifecycle("extend", { "seconds" => seconds }, false, idempotency_key)
144
-
145
- # Days (1 to 365) a paused sandbox is kept before it is deleted.
146
- def set_retention(days, idempotency_key: nil) = lifecycle("retention", { "days" => days }, false, idempotency_key)
147
-
148
- # Starts a stopped persistent sandbox again from its disk. Memory is not kept.
149
- # Waits for room like +wake+ when its server is full.
150
- def restart(wait: true, idempotency_key: nil, wait_for_capacity: nil)
151
- lifecycle("restart", {}, wait, idempotency_key, room: room_for(wait_for_capacity))
152
- end
153
-
154
- # Changes name, labels, auto_wake, user ("sandbox" or "root": who later
155
- # commands run as when one names no user), lease_seconds (with no time
156
- # limit, how far ahead each renewal funds it, 300 to 43200),
157
- # idle_pause_seconds, persistent or
158
- # max_total_cost_micros; fields left out stay as they are, and
159
- # +max_total_cost_micros: :remove+ removes the cap.
160
- def update(idempotency_key: nil, **settings)
161
- body = Fields.body(settings.reject { |_key, value| value == :remove })
162
- body["maxTotalCostMicros"] = nil if settings[:max_total_cost_micros] == :remove
163
- lifecycle("update", body, false, idempotency_key)
164
- end
165
-
166
- # Keeps a sandbox with a time limit running past it on a background thread,
167
- # until +stop+ or +stop_keep_alive+: every +every+ seconds it extends the
168
- # limit so that +margin+ seconds remain, never more than the hour ahead the
169
- # API allows. A sandbox with no time limit needs none and is only watched.
170
- # Running time is billed as it is used. A paused sandbox is left paused; a
171
- # stopped or deleted one ends the loop.
172
- def keep_alive(every: 60, margin: ApiDefaults::KEEP_ALIVE_MARGIN_SECONDS, &on_error)
173
- stop_keep_alive
174
- every = [10, every].max
175
- margin = margin.clamp(60, 3600)
176
- @keep_alive = Thread.new do
177
- loop do
178
- begin
179
- refresh
180
- break if %w[stopped stopping].include?(state)
181
-
182
- expires = Sandbox.limit_end(@info)
183
- if state == "running" && expires
184
- need = (margin - (Time.parse(expires) - Time.now)).ceil
185
- extend_lease([3600, need].min) if need >= 1
186
- end
187
- rescue Error => e
188
- # Gone (deleted elsewhere, or by its own time limit): nothing to
189
- # keep alive, and asking again would only be refused.
190
- break if e.status == 404
191
-
192
- on_error&.call(e)
193
- end
194
- sleep(every)
195
- end
196
- end
197
- @keep_alive.report_on_exception = false
198
- self
199
- end
200
-
201
- # Where a sandbox's time limit ends, or nil when it has none: it renews
202
- # itself (timeoutSeconds 0, or persistent) unless endsAt says its renewal
203
- # stopped. An older server sends no endsAt and a timeout of at least a
204
- # minute.
205
- def self.limit_end(info)
206
- return info["endsAt"] if info["endsAt"]
207
- return nil if info["timeoutSeconds"].to_i.zero? || info["persistent"]
208
-
209
- info["expiresAt"]
210
- end
211
-
212
- # Ends a keep-alive, if one runs.
213
- def stop_keep_alive
214
- thread = @keep_alive
215
- @keep_alive = nil
216
- thread&.kill
217
- end
218
-
219
- # Starts copies of this sandbox as it is now (files, memory, running
220
- # processes), each its own sandbox, on its server while it has room and on
221
- # another when it is full, answered once they run. One copy without +count+; an array with it. If a copy fails, the
222
- # error's +details["startedSandboxIds"]+ names the copies that did start.
223
- # +funding+ is accepted and ignored: copies run on free usage first, then credit.
224
- # +secrets: [name, ...]+ is the egress secrets the copies may use, by name:
225
- # only those of your egress secrets that would otherwise reach them. +[]+
226
- # is none; leave it out to keep this sandbox's list. Fixed for the copies'
227
- # life; it may only narrow this sandbox's list.
228
- def fork(count: nil, name: nil, labels: nil, keep_snapshot: nil, funding: nil, secrets: nil,
229
- idempotency_key: nil)
230
- body = Fields.body(count: count, name: name, labels: labels, keep_snapshot: keep_snapshot,
231
- secrets: secrets&.to_a)
232
- # Its key replays a refusal for room or a limit, so it is told at once.
233
- reply = @t.json("POST", path(":fork"), body: body, wait: 60, key: idempotency_key, room: 0)
234
- copies = reply["sandboxes"].map { |info| Sandbox.new(@t, info) }
235
- count.nil? ? copies.first : copies
236
- end
237
-
238
- # Keeps this sandbox's whole machine as a snapshot to start new sandboxes
239
- # from. A running sandbox is paused by the server for the moment it takes
240
- # and woken once the capture is over (one still capturing when the call
241
- # answers stays paused until it is ready); a paused one stays paused. A
242
- # sandbox with volumes cannot be snapshotted.
243
- def snapshot(name: nil, labels: nil, retention_days: nil, idempotency_key: nil)
244
- refresh
245
- # Straight after a fork or a wake the sandbox is still resuming, and
246
- # after a pause still pausing: wait for where it is going, or a
247
- # snapshot of it is refused as not paused.
248
- if %w[resuming starting].include?(state) then wait_for("running")
249
- elsif state == "pausing" then wait_for("paused")
250
- end
251
- # The server pauses a running sandbox itself: a client pause and wake
252
- # would be two more round trips.
253
- Record.new(@t.json("POST", path(":snapshot"),
254
- body: Fields.body(name: name, labels: labels, retention_days: retention_days),
255
- wait: 10, key: idempotency_key))
256
- end
257
-
258
- # CPU and memory over a range: 15m, 1h, 6h, 24h, 7d or 30d.
259
- def metrics(range: nil) = Record.new(@t.json("GET", path("/metrics"), query: { "range" => range }))
260
-
261
- # Runs a command and returns its exit code and output. A String runs under
262
- # +bash -c+; an Array runs the program directly, with no shell.
263
- #
264
- # +cwd+ (default /workspace), +user+ ("sandbox", the default, or "root",
265
- # through the sandbox's passwordless sudo), +env+ (merged over the
266
- # sandbox's; put secrets here), +stdin+, +timeout+ (seconds, default 60, up
267
- # to a day; a timeout is a result, not an error), +on_stdout+ and
268
- # +on_stderr+ (stream the command; the result keeps everything), and
269
- # +check+ (raise CommandError on a non-zero exit or a timeout), and
270
- # +trace_files+ (the result's +files+ are the files it read and wrote; an
271
- # older sandbox says to stop and start it, and no command runs).
272
- def exec(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
273
- check: false, idempotency_key: nil, trace_files: false)
274
- streamed = on_stdout || on_stderr || (timeout && timeout > 60)
275
- result = if streamed
276
- collect(exec_stream(command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
277
- idempotency_key: idempotency_key, trace_files: trace_files), on_stdout, on_stderr)
278
- else
279
- body = command_body(command, cwd, env, stdin, timeout, user, trace_files)
280
- CommandResult.new(@t.json("POST", path(":exec"), body: body, key: idempotency_key,
281
- timeout: timeout && (timeout + 60)))
282
- end
283
- raise CommandError, result if check && !result.ok?
284
-
285
- result
286
- end
287
-
288
- # Runs a command and yields its events as they happen: start, stdout,
289
- # stderr, exit (each a Hash). Resumes by itself when the server ends a long
290
- # stream, so it never drops output. Without a block, an Enumerator.
291
- def exec_stream(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, trace_files: false, &block)
292
- unless block
293
- return enum_for(:exec_stream, command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
294
- idempotency_key: idempotency_key, trace_files: trace_files)
295
- end
296
-
297
- longest = ApiDefaults::STREAMED_EXEC_TIMEOUT_SECONDS
298
- body = command_body(command, cwd, env, stdin, timeout || longest, user, trace_files).merge("stream" => true)
299
- handed_over = nil
300
- process_id = nil
301
- cursor = 0
302
- exited = false
303
- begin
304
- @t.events("POST", path(":exec"), body: body, key: idempotency_key,
305
- timeout: timeout ? timeout + 60 : longest) do |event|
306
- case event["type"]
307
- when "continue" then handed_over = event
308
- when "error" then raise stream_error(event)
309
- else
310
- process_id = event["processId"] if event["type"] == "start"
311
- cursor = event["offset"] + event["data"].bytesize if %w[stdout stderr].include?(event["type"])
312
- exited = true if event["type"] == "exit"
313
- yield event
314
- end
315
- break if handed_over || exited
316
- end
317
- rescue ConnectionError => e
318
- raise if e.code != "connection_error" || process_id.nil?
319
- end
320
- return follow(handed_over["processId"], handed_over["cursor"], &block) if handed_over
321
- return if exited
322
-
323
- # The stream closed before the command's exit. Its output is kept on the
324
- # sandbox, so follow it from where this stream stopped; an end with no
325
- # exit is never a result.
326
- if process_id.nil?
327
- raise ConnectionError.new("The exec stream closed before the command started.",
328
- code: "connection_error", idempotency_key: idempotency_key,
329
- hint: "Run it again; to be sure it runs once, pass the same idempotency_key.")
330
- end
331
- follow(process_id, cursor, &block)
332
- end
333
-
334
- # A process's output events from +cursor+ until it exits, across the
335
- # server's stream slices. A stream that closes or is cut before the exit
336
- # is followed again from where it stopped; four in a row with nothing new
337
- # are an error, never an end.
338
- def follow(process_id, cursor = 0)
339
- return enum_for(:follow, process_id, cursor) unless block_given?
340
-
341
- idle = 0
342
- loop do
343
- resume = nil
344
- exited = false
345
- before = cursor
346
- cut = false
347
- begin
348
- @t.events("GET", path("/processes/#{Transport.segment(process_id)}/output"),
349
- query: { "cursor" => cursor, "follow" => "true" }, timeout: 180) do |event|
350
- case event["type"]
351
- when "continue"
352
- resume = event["cursor"]
353
- break
354
- when "stdout", "stderr" then cursor = event["offset"] + event["data"].bytesize
355
- when "error" then raise stream_error(event)
356
- when "exit" then exited = true
357
- end
358
- yield event
359
- break if exited
360
- end
361
- rescue ConnectionError => e
362
- raise if e.code != "connection_error"
363
-
364
- cut = true
365
- end
366
- break if exited
367
-
368
- cursor = [cursor, resume].max if resume
369
- if resume || cursor > before
370
- idle = 0
371
- next
372
- end
373
- idle += 1
374
- if idle > 3
375
- raise ConnectionError.new("The output stream of process #{process_id} keeps closing before it ends.",
376
- code: "connection_error",
377
- hint: "Read what it printed so far: runtime sandboxes logs #{id} #{process_id}")
378
- end
379
- sleep([0.05 * (2**idle), 2].min) if cut
380
- end
381
- end
382
-
383
- # Starts a background process (a server, a watcher, a REPL) and returns at
384
- # once. It outlives your connection; +process(id)+ gets it back.
385
- # +pipe_stdin: true+ keeps input open for +write+; +pty: { cols:, rows: }+
386
- # gives it a terminal; +trace_files: true+ records the files it opens, read
387
- # them with +files+ once it has ended.
388
- def spawn(command, cwd: nil, user: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil,
389
- idempotency_key: nil, trace_files: false)
390
- body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout, user, trace_files)
391
- body["stdinMode"] = "pipe" if pipe_stdin
392
- body["pty"] = Fields.body(pty) if pty
393
- SandboxProcess.new(self, @t.json("POST", path("/processes"), body: body, key: idempotency_key))
394
- end
395
-
396
- # The sandbox's background processes.
397
- def processes = @t.json("GET", path("/processes"))["data"].map { |info| Record.new(info) }
398
-
399
- # Gets a background process back by id.
400
- def process(id) = SandboxProcess.new(self, @t.json("GET", path("/processes/#{Transport.segment(id)}")))
401
-
402
- def inspect = "#<WithRuntime::Sandbox #{id} #{state}>"
403
-
404
- private
405
-
406
- def lifecycle(verb, body, wait, key, room: nil)
407
- @info = Record.new(@t.json("POST", path(":#{verb}"), body: body, wait: wait ? 60 : 0, key: key, room: room))
408
- self
409
- end
410
-
411
- def room_for(wait_for_capacity) = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
412
-
413
- def command_body(command, cwd, env, stdin, timeout, user, trace_files = false)
414
- body = command.is_a?(Array) ? { "argv" => command.map(&:to_s) } : { "command" => command.to_s }
415
- body["cwd"] = cwd if cwd
416
- body["user"] = user.to_s if user
417
- body["env"] = env.to_h { |key, value| [key.to_s, value.to_s] } if env
418
- body["stdinBase64"] = [stdin.to_s.b].pack("m0") unless stdin.nil?
419
- body["timeoutMs"] = (timeout * 1000).round if timeout
420
- body["traceFiles"] = true if trace_files
421
- body
422
- end
423
-
424
- def collect(events, on_stdout, on_stderr)
425
- stdout = +""
426
- stderr = +""
427
- fields = {}
428
- dropped = false
429
- events.each do |event|
430
- case event["type"]
431
- when "start" then fields["processId"] = event["processId"]
432
- when "stdout"
433
- stdout << event["data"]
434
- on_stdout&.call(event["data"])
435
- when "stderr"
436
- stderr << event["data"]
437
- on_stderr&.call(event["data"])
438
- when "truncated" then dropped = true
439
- when "exit" then fields.merge!(event.slice("exitCode", "timedOut", "durationMs", "files"))
440
- end
441
- end
442
- # A truncated event does not say which stream lost bytes, so both flags carry it.
443
- CommandResult.new(fields.merge("stdout" => stdout, "stderr" => stderr,
444
- "stdoutTruncated" => dropped, "stderrTruncated" => dropped))
445
- end
446
-
447
- def stream_error(event)
448
- error = event["error"].is_a?(Hash) ? event["error"] : {}
449
- Error.new(error["message"] || "The output stream failed.", code: error["code"] || "stream_failed",
450
- request_id: error["requestId"])
451
- end
452
- end
453
-
454
- # A background process in a sandbox: its output, its input, its end. Use one
455
- # from one thread at a time.
456
- class SandboxProcess
457
- attr_reader :info
458
-
459
- def initialize(sandbox, info)
460
- @sandbox = sandbox
461
- @info = Record.new(info)
462
- @input_offset = info["stdinOffset"].to_i
463
- end
464
-
465
- def id = @info["id"]
466
-
467
- # Every output event from +cursor+ (0 for the start) until the process exits.
468
- def output(cursor = 0, &block) = @sandbox.follow(id, cursor, &block)
469
-
470
- # Waits for the process to end and returns its result.
471
- def wait
472
- stdout = +""
473
- stderr = +""
474
- fields = { "processId" => id }
475
- dropped = false
476
- output(0) do |event|
477
- case event["type"]
478
- when "stdout" then stdout << event["data"]
479
- when "stderr" then stderr << event["data"]
480
- when "truncated" then dropped = true
481
- when "exit" then fields.merge!(event.slice("exitCode", "timedOut", "durationMs"))
482
- end
483
- end
484
- CommandResult.new(fields.merge("stdout" => stdout, "stderr" => stderr,
485
- "stdoutTruncated" => dropped, "stderrTruncated" => dropped))
486
- end
487
-
488
- # Sends input. Offsets are tracked for you, so a retried write is never
489
- # typed twice. +eof: true+ closes the input after it.
490
- def write(data, eof: false)
491
- data = data.to_s.b
492
- sent = 0
493
- loop do
494
- body = { "base64" => [data.byteslice(sent..)].pack("m0"), "offset" => @input_offset }
495
- body["eof"] = true if eof
496
- reply = @sandbox.transport.json("POST", path(":write"), body: body)
497
- progress = reply["offset"] - @input_offset
498
- sent += progress
499
- @input_offset = reply["offset"]
500
- return self if sent >= data.bytesize
501
- raise Error.new("The process took none of the input.", code: "write_stalled") if progress <= 0
502
- end
503
- end
504
-
505
- # Sends a signal: SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT, SIGUSR1 or SIGUSR2.
506
- def kill(signal = "SIGTERM") = @sandbox.transport.json("POST", path(":signal"), body: { "signal" => signal })
507
-
508
- # Changes a PTY process's terminal size.
509
- def resize(cols, rows) = @sandbox.transport.json("POST", path(":resize"), body: { "cols" => cols, "rows" => rows })
510
-
511
- # The files a process spawned with +trace_files: true+ read and wrote. Fails
512
- # with process_running while it runs.
513
- def files = TracedFiles.new(@sandbox.transport.json("GET", path("/files")))
514
-
515
- # Reads the process again.
516
- def refresh
517
- @info = Record.new(@sandbox.transport.json("GET", path))
518
- self
519
- end
520
-
521
- private
522
-
523
- def path(suffix = "") = @sandbox.path("/processes/#{Transport.segment(id)}#{suffix}")
524
- end
525
-
526
- # +sbx.files+: files in a sandbox. Paths are absolute; any path the sandbox user may use.
527
- class Files
528
- CHUNK = 1 << 20
529
-
530
- def initialize(sandbox)
531
- @sandbox = sandbox
532
- end
533
-
534
- # A file's bytes (a binary String), any size.
535
- def read(path) = t.file_bytes(@sandbox.path("/files/content"), query: { "path" => path })
536
-
537
- def read_text(path) = read(path).force_encoding(Encoding::UTF_8)
538
-
539
- # Writes a file of any size, atomically, making parent directories. A file
540
- # over 1 MiB goes in parallel 1 MiB chunks checked against its SHA-256.
541
- def write(path, data, mode: nil, idempotency_key: nil)
542
- data = data.to_s.b
543
- mode = mode_string(mode) unless mode.nil?
544
- if data.bytesize <= CHUNK
545
- t.bytes("PUT", @sandbox.path("/files/content"), query: { "path" => path, "mode" => mode }.compact, raw: data, key: idempotency_key)
546
- return nil
547
- end
548
- root = idempotency_key || SecureRandom.uuid
549
- phase = ->(name) { Digest::SHA256.hexdigest("files.write:#{root}:#{name}") }
550
- body = { "path" => path, "size" => data.bytesize, "sha256" => Digest::SHA256.hexdigest(data), "mode" => mode }.compact
551
- begin
552
- upload = t.json("POST", @sandbox.path("/uploads"), body: body, key: phase.call("begin"))
553
- rescue Error => error
554
- raise unless mode && error.code == "guest_upgrade_required"
555
- upload = t.json("POST", @sandbox.path("/uploads"), body: body.reject { |key, _| key == "mode" }, key: phase.call("legacy-begin"))
556
- end
557
- chunk = upload["chunkBytes"].to_i
558
- raise Error.new("The upload omitted its ID or chunk size.", code: "unexpected_answer") unless chunk.positive? && upload["uploadId"]
559
- base = @sandbox.path("/uploads/#{Transport.segment(upload["uploadId"])}")
560
- commit = -> { t.json("POST", "#{base}:commit", body: {}, key: phase.call("commit")) }
561
- committed = false
562
- if upload["replayed"]
563
- begin
564
- commit.call
565
- committed = true
566
- rescue Error => error
567
- raise unless error.code == "upload_incomplete"
568
- end
569
- end
570
- unless committed
571
- offsets = Queue.new
572
- (0...data.bytesize).step(chunk) { |offset| offsets << offset }
573
- offsets.close
574
- failure = nil
575
- lock = Mutex.new
576
- workers = Array.new(4) do
577
- Thread.new do
578
- while !lock.synchronize { failure } && (offset = offsets.pop)
579
- begin
580
- t.bytes("PUT", base, query: { "offset" => offset }, raw: data.byteslice(offset, chunk))
581
- rescue StandardError => error
582
- lock.synchronize { failure ||= error }
583
- end
584
- end
585
- end
586
- end
587
- begin
588
- workers.each(&:join)
589
- raise failure if failure
590
- commit.call
591
- rescue StandardError
592
- begin
593
- t.json("POST", "#{base}:abort", body: {}, key: phase.call("abort"), timeout: 10)
594
- rescue Error
595
- nil
596
- end
597
- raise
598
- end
599
- end
600
- t.json("POST", @sandbox.path("/files:chmod"), body: { "path" => path, "mode" => mode }, key: phase.call("chmod")) if mode && upload["mode"] != mode
601
- nil
602
- end
603
-
604
- def chmod(path, mode)
605
- t.json("POST", @sandbox.path("/files:chmod"), body: { "path" => path, "mode" => mode_string(mode) })
606
- nil
607
- end
608
- def watches = WatchService.new(@sandbox)
609
- def watch(path, **options) = watches.start(path, **options)
610
- def mode_string(mode)
611
- raise ArgumentError, "mode must be an integer from 000 to 777" unless mode.is_a?(Integer) && mode.between?(0, 0o777)
612
- format("%03o", mode)
613
- end
614
- private :mode_string
615
-
616
- # A directory's entries (default /workspace). +depth:+ goes deeper; +glob:+
617
- # filters, e.g. "**/*.py".
618
- def list(directory = "/workspace", depth: nil, glob: nil, hidden: nil, limit: nil)
619
- query = { "path" => directory, "depth" => depth, "glob" => glob, "hidden" => hidden, "limit" => limit }
620
- t.json("GET", @sandbox.path("/files/list"), query: query)["data"].map { |entry| Record.new(entry) }
621
- end
622
-
623
- def glob(pattern, root = "/workspace") = list(root, glob: pattern)
624
-
625
- # A file's entry, or nil when it does not exist.
626
- def stat(path)
627
- answer = t.json("GET", @sandbox.path("/files/stat"), query: { "path" => path })
628
- answer["exists"] ? Record.new(answer) : nil
629
- end
630
-
631
- def exist?(path) = !stat(path).nil?
632
-
633
- def mkdir(path, parents: true)
634
- t.json("POST", @sandbox.path("/files:mkdir"), body: { "path" => path, "parents" => (parents || nil) }.compact)
635
- nil
636
- end
637
-
638
- # Removes a file, or a directory with +recursive: true+. Says whether anything was there.
639
- def remove(path, recursive: false)
640
- body = { "path" => path, "recursive" => (recursive || nil) }.compact
641
- t.json("POST", @sandbox.path("/files:remove"), body: body)["removed"] == true
642
- end
643
-
644
- def rename(from, to, overwrite: false)
645
- body = { "from" => from, "to" => to, "overwrite" => (overwrite || nil) }.compact
646
- t.json("POST", @sandbox.path("/files:rename"), body: body)
647
- nil
648
- end
649
-
650
- # A link anyone can open with no API key to download +path+ (a Hash with
651
- # "url" and "expiresAt"). Range works. It lasts an hour by default, at most
652
- # 7 days (+expires_in_seconds+). +filename+ saves it under that name;
653
- # +wake+ true wakes a paused sandbox, false never does; +archive+ links a
654
- # folder as a .tar.gz.
655
- def download_url(path, expires_in_seconds: nil, filename: nil, wake: nil, archive: nil)
656
- body = { "path" => path, "method" => "GET", "expiresInSeconds" => expires_in_seconds,
657
- "filename" => filename, "wake" => wake, "archive" => archive }.compact
658
- t.json("POST", @sandbox.path("/files:link"), body: body)
659
- end
660
-
661
- # A link anyone can PUT a raw body to with no API key: the body becomes the
662
- # file at +path+, whole or not at all, up to +max_bytes+ (5 GiB at most).
663
- def upload_url(path, expires_in_seconds: nil, max_bytes: nil, wake: nil)
664
- body = { "path" => path, "method" => "PUT", "expiresInSeconds" => expires_in_seconds,
665
- "maxBytes" => max_bytes, "wake" => wake }.compact
666
- t.json("POST", @sandbox.path("/files:link"), body: body)
667
- end
668
-
669
- # Ends every link made for this sandbox so far.
670
- def revoke_links = t.json("POST", @sandbox.path("/files:revoke-links"))
671
-
672
- # Copies a local file or directory in. A directory travels as one gzipped
673
- # tar to the API's folder routes, unpacked by the sandbox's own tar as it
674
- # arrives.
675
- def upload(local, remote)
676
- return write(remote, File.binread(local)) unless File.directory?(local)
677
-
678
- archive = Tar.pack_directory(local)
679
- if archive.bytesize <= CHUNK
680
- t.bytes("PUT", @sandbox.path("/files/archive"), query: { "path" => remote }, raw: archive)
681
- return nil
682
- end
683
- # Larger: parts in order; a part resent after a lost answer is not written twice.
684
- upload = t.json("POST", @sandbox.path("/files/archive/uploads"), body: { "path" => remote, "gzip" => true })
685
- base = @sandbox.path("/files/archive/uploads/#{Transport.segment(upload["uploadId"])}")
686
- begin
687
- (0...archive.bytesize).step(upload["chunkBytes"].to_i) do |offset|
688
- t.bytes("PUT", base, query: { "offset" => offset }, raw: archive.byteslice(offset, upload["chunkBytes"].to_i))
689
- end
690
- t.json("POST", "#{base}:commit", body: {})
691
- rescue StandardError
692
- begin
693
- t.json("POST", "#{base}:abort", body: {}, timeout: 10)
694
- rescue Error
695
- nil
696
- end
697
- raise
698
- end
699
- nil
700
- end
701
-
702
- # Copies a file or directory out. A directory comes as one tar from the
703
- # API's folder route.
704
- def download(remote, local)
705
- entry = stat(remote)
706
- raise NotFoundError.new("#{remote} does not exist.", code: "file_not_found", status: 404) unless entry
707
-
708
- if entry["type"] != "directory"
709
- FileUtils.mkdir_p(File.dirname(File.expand_path(local)))
710
- File.binwrite(local, read(remote))
711
- return nil
712
- end
713
- # The sandbox's own tar packs it as it streams, and it is unpacked as it
714
- # arrives; one cut short is refused and nothing is put in place.
715
- unpacker = Tar::Unpacker.new(local)
716
- begin
717
- t.chunks(@sandbox.path("/files/archive"), query: { "path" => remote, "gzip" => true }) { |chunk| unpacker.feed(chunk) }
718
- unpacker.finish
719
- ensure
720
- unpacker.discard
721
- end
722
- nil
723
- end
724
-
725
- private
726
-
727
- def t = @sandbox.transport
728
- end
729
-
730
- # +sbx.previews+: share ports of the sandbox at public HTTPS addresses under
731
- # runtimehost.com. WebSockets work; the server must listen on 0.0.0.0 or localhost.
732
- class Previews
733
- def initialize(sandbox)
734
- @sandbox = sandbox
735
- end
736
-
737
- # Shares +port+, or changes its visibility and embed origins if it is
738
- # shared already. +visibility+ is "private" (the default: a token is
739
- # needed) or "public"; +ttl_seconds+ is how long the returned token lasts
740
- # (60 s to 7 days). +embed_origins+ names the sites that may show it in an
741
- # iframe (["https://app.example.com", "https://*.example.com"]); any other
742
- # site's iframe is refused. Omitted, a shared port keeps its list; [] is
743
- # any site, the default.
744
- def create(port, visibility: nil, ttl_seconds: nil, embed_origins: nil)
745
- body = { "port" => port, "visibility" => visibility, "ttlSeconds" => ttl_seconds,
746
- "embedOrigins" => embed_origins }.compact
747
- Record.new(t.json("POST", path, body: body))
748
- end
749
-
750
- # Every shared port, each private one with a fresh token.
751
- def list = t.json("GET", path)["data"].map { |preview| Record.new(preview) }
752
-
753
- # One preview, with a fresh token of +ttl_seconds+ if it is private.
754
- def get(port, ttl_seconds: nil) = Record.new(t.json("GET", path("/#{port.to_i}"), query: { "ttlSeconds" => ttl_seconds }))
755
-
756
- # Refuses every token issued for this port so far and returns a new one.
757
- def rotate(port) = Record.new(t.json("POST", path("/#{port.to_i}:rotate")))
758
-
759
- # Stops sharing +port+. Open connections close within seconds.
760
- def delete(port)
761
- t.json("DELETE", path("/#{port.to_i}"))
762
- nil
763
- end
764
-
765
- private
766
-
767
- def t = @sandbox.transport
768
- def path(suffix = "") = @sandbox.path("/previews#{suffix}")
769
- end
770
- end