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