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,17 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module WithRuntime
4
- # Every value this SDK sends the API for a bounded time field when the caller
5
- # names none, in one place. packages/cloud/tests/sdk-defaults.test.ts holds
6
- # each inside the range the API's registry gives that field, and the same
7
- # names in the JavaScript, Python, Go and Java SDKs to theirs. The suffix is
8
- # the unit; a new default goes here, under a name that test maps to its field.
9
- module ApiDefaults
10
- # A server-side wait for a state (GET /v1/sandboxes/{id}?waitFor=).
11
- WAIT_FOR_TIMEOUT_SECONDS = 60
12
- # A streamed exec's command limit when none is given: the API's longest.
13
- STREAMED_EXEC_TIMEOUT_SECONDS = 86_400
14
- # The time keep_alive keeps ahead of a time limit, and so the most it extends by.
15
- KEEP_ALIVE_MARGIN_SECONDS = 600
16
- end
17
- end
@@ -1,377 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require "securerandom"
4
-
5
- module WithRuntime
6
- # A product built on the five verbs every resource shares (create, get,
7
- # list, update, delete) and following one to a state: the same rules as the
8
- # JavaScript SDK's resources.ts. One deadline covers a write, its retries
9
- # and every read after it.
10
- class ResourceProduct < Product
11
- # A whole wait's deadline and its pause between reads.
12
- class Following
13
- attr_reader :key
14
-
15
- def initialize(timeout, poll, key)
16
- @poll = poll
17
- @key = key
18
- @deadline = timeout.positive? ? now + timeout : nil
19
- end
20
-
21
- # Seconds left for a call, or nil when the wait has no deadline (the
22
- # client's own timeout then bounds each call).
23
- def left = @deadline && [@deadline - now, 0.001].max
24
-
25
- def expired? = !@deadline.nil? && now >= @deadline
26
-
27
- def pause
28
- sleep(@deadline ? [@poll, [@deadline - now, 0].max].min : @poll)
29
- raise timed_out if expired?
30
- end
31
-
32
- def timed_out
33
- ConnectionError.new("Waiting was cancelled or reached its deadline; the resource may still change.",
34
- code: "timeout", idempotency_key: key,
35
- hint: "Read the resource to resume waiting. Retry a write with the same idempotency_key.")
36
- end
37
-
38
- private
39
-
40
- def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
41
- end
42
-
43
- # +path+ is the product's path (/v1/apps); a wait ends at its target or at
44
- # any of +settled+, which raises the resource's own error.
45
- def initialize(transport, path, settled)
46
- super(transport)
47
- @base = path
48
- @settled = settled
49
- end
50
-
51
- # Creates one; defaults belong to the API, so the SDK sends none.
52
- def create(idempotency_key: nil, **fields)
53
- Record.new(@t.json("POST", @base, body: Fields.body(fields), key: idempotency_key))
54
- end
55
-
56
- # With +wait_for:+ the API holds the answer until that state or
57
- # +timeout_seconds+ (1 to 60; 30 by default) pass. Check the state it returns.
58
- def get(id, wait_for: nil, timeout_seconds: nil)
59
- read(id, { "waitFor" => wait_for, "timeoutSeconds" => timeout_seconds },
60
- wait_for && ((timeout_seconds || 30) + 60))
61
- end
62
-
63
- # +label:+ is key:value filters that all must match; +state:+ defaults to
64
- # the product's live states; +limit:+ 1 to 100 (50).
65
- def list(name: nil, label: nil, state: nil, limit: nil, cursor: nil)
66
- page(@base, { "name" => name, "label" => label, "state" => state, "limit" => limit, "cursor" => cursor })
67
- end
68
-
69
- # Fields left out stay as they are; +name: :remove+ clears the name.
70
- def update(id, idempotency_key: nil, **changes)
71
- Record.new(@t.json("POST", "#{@base}/#{seg(id)}:update", body: patch(changes), key: idempotency_key))
72
- end
73
-
74
- # Follows the resource's state to +target+, reading it every +poll+
75
- # seconds (0.25) for at most +timeout+ seconds in all (300; 0 waits as long
76
- # as it takes). Raises the resource's error when it settles elsewhere, and
77
- # ConnectionError with code timeout at the deadline.
78
- def wait(id, target, timeout: 300, poll: 0.25)
79
- following(timeout, poll, nil) { |wait| follow(id, target, wait) }
80
- end
81
-
82
- # Deletes it. With +wait: true+, follows it to deleted under one
83
- # idempotency key made before the first try, so a timed-out delete can be
84
- # retried after a restart with the key its error carries.
85
- def delete(id, wait: false, timeout: 300, poll: 0.25, idempotency_key: nil)
86
- return remove(id, idempotency_key, nil) unless wait
87
-
88
- key = idempotency_key || SecureRandom.uuid
89
- following(timeout, poll, key) { |follow| follow(id, "deleted", follow, remove(id, key, follow.left)) }
90
- end
91
-
92
- private
93
-
94
- def read(id, query = nil, timeout = nil)
95
- Record.new(@t.json("GET", "#{@base}/#{seg(id)}", query: query, timeout: timeout))
96
- end
97
-
98
- def remove(id, key, timeout) = Record.new(@t.json("DELETE", "#{@base}/#{seg(id)}", key: key, timeout: timeout))
99
-
100
- def follow(id, target, wait, initial = nil)
101
- record = initial || read(id, nil, wait.left)
102
- loop do
103
- return record if record.state == target
104
- if @settled.include?(record.state)
105
- error = record["error"].is_a?(Hash) ? record["error"] : {}
106
- raise Error.new(error["message"] || "Expected #{target}, but #{id} reached #{record.state}.",
107
- code: error["code"] || "unexpected_state", idempotency_key: wait.key,
108
- hint: "Read the resource and inspect its error before starting another change.",
109
- details: { "id" => id, "state" => record.state, "target" => target, "resource" => record.to_h })
110
- end
111
- wait.pause
112
- record = read(id, nil, wait.left)
113
- end
114
- end
115
-
116
- # One deadline covers the write, retries and every read. A read's failure
117
- # still belongs to the write that started the wait, so it carries its key.
118
- def following(timeout, poll, key)
119
- check(timeout, "timeout")
120
- check(poll, "poll")
121
- wait = Following.new(timeout, poll, key)
122
- begin
123
- result = yield wait
124
- raise wait.timed_out if wait.expired?
125
-
126
- result
127
- rescue Error => e
128
- raise wait.timed_out if wait.expired?
129
- raise e if key.nil? || e.idempotency_key
130
-
131
- raise e.class.new(e.message, code: e.code, status: e.status, hint: e.hint, request_id: e.request_id,
132
- details: e.details, idempotency_key: key, retry_after: e.retry_after)
133
- end
134
- end
135
-
136
- def check(value, field)
137
- return if value.is_a?(Numeric) && value.finite? && !value.negative?
138
-
139
- raise Error.new("#{field} must be a finite, nonnegative number.", code: "invalid_request",
140
- hint: "Fix the option and call again; nothing was sent.",
141
- details: { "field" => field })
142
- end
143
- end
144
-
145
- # +runtime.apps+ and +runtime.functions+: your server, deployed from an
146
- # image or a build, kept running in copies (an App keeps +min_copies+ awake;
147
- # a Function sleeps to zero). In a private beta: an account outside it is
148
- # refused with product_in_beta (403, PermissionDeniedError).
149
- #
150
- # app = runtime.apps.create(name: "web", max_copies: 3, vcpu: 1, memory_mib: 1024)
151
- # deploy = runtime.apps.deploy(app.id, image: "web:latest", env: { "MODE" => "prod" }, wait: true)
152
- # puts deploy.url
153
- #
154
- # An App or Function: id, name, url (its address for life, its name then
155
- # its account's: https://shop-3f9a1c2e7b04d915-acme1.runtimehost.com/; a rename leaves it,
156
- # and its id's address answers too), labels, state (waiting, live, failed,
157
- # deleting, deleted), min_copies, max_copies, concurrency, spares, vcpu,
158
- # memory_mib, port, health_path, cdn, live_version, previous_version, error
159
- # ({code, message} or nil), line (while a copy waits for room: lane,
160
- # place, ahead by lane and words; nil otherwise), created_at, updated_at,
161
- # deleted_at, and release_watch (alert, the default; rollback; or off). An App
162
- # also has release_stages (at_once, the default, or staged), release_soak_seconds
163
- # (60 to 3600) and staged_release (its staged release under way or its last:
164
- # version, from, state rolling/back/done/failed/ended, stage, stages, copies,
165
- # of, soak_seconds, detail, started_at, updated_at; nil before its first). A
166
- # Function also has sleep_after_ms (250 to 5000).
167
- #
168
- # A deploy: id, version, url and state (building, warming, switching, live,
169
- # failed, superseded); a failed or superseded one has error with code
170
- # (deploy_build_failed, deploy_health_failed, deploy_stop_failed,
171
- # deploy_stage_failed, deploy_switch_failed, deploy_superseded), message, hint and last_output. A version: version,
172
- # live, previous, saved, deploy (its deploy's id) and build (nil for an
173
- # image). A copy: id, version,
174
- # region, state (starting, serving, draining, frozen, parked) and since.
175
- class Apps < ResourceProduct
176
- DEPLOY_ENDED = %w[live failed superseded].freeze
177
- # Reconnections in a row with no new line before a log follow gives up.
178
- LOG_RECONNECTS = 3
179
- LOG_SEEN = 10_000
180
-
181
- # +path+: /v1/apps or /v1/functions.
182
- def initialize(transport, path = "/v1/apps")
183
- super(transport, path, %w[failed deleted live])
184
- end
185
-
186
- # Creates one waiting for its first version: +max_copies:+ (1 to the account's App copies at once, its plan's sandboxes at once),
187
- # +vcpu:+ (1 to 16) and +memory_mib:+ (128 to 65536) are required;
188
- # +concurrency:+, +spares:+, +port:+ (8080), +health_path:+, +cdn:+ (true: Cloudflare's CDN in
189
- # front of its addresses; false sends visitors straight to Runtime's routers,
190
- # nothing cached), +name:+, +labels:+, +release_watch:+ ("alert" by default: tell the
191
- # owners when a new version gets clearly worse in its first 15 minutes; "rollback" also
192
- # goes back to the previous version; "off" does neither), and for an App
193
- # +min_copies:+ (0). An App also takes +release_stages:+ ("at_once" by default;
194
- # "staged" starts one copy of a new version beside the live version's, then
195
- # about 10%, 50% and all of them, each stage judged on its visitors' errors
196
- # and speed before the next; a stage that does worse goes back, its copies
197
- # drain and the deploy fails with deploy_stage_failed, the live version never
198
- # stopping) and +release_soak_seconds:+ (60 to 3600, default 300: how long
199
- # each stage runs once its copies serve). A Function leaves +min_copies+ out, zero included.
200
- # A Function also takes +sleep_after_ms:+ (250 to 5000, default 1000): at
201
- # most how long a copy stays awake after its last request ends; awake time
202
- # with no request in flight is not billed. An App is refused it.
203
- def create(idempotency_key: nil, **fields) = super
204
-
205
- # Follows resource state, not a deploy: an older live version can survive
206
- # a failed rollout of a newer one. +target+ is "live" or "deleted".
207
- def wait(id, target, timeout: 300, poll: 0.25) = super
208
-
209
- # Deploys a new version from +image:+ (an image of this account: id,
210
- # name, name:tag or name@version, ready) or +build:+ (a build's id), with
211
- # +env:+, +port:+ and +health_path:+. +keep_env: true+ carries the last
212
- # deploy's environment, still sealed, with +env:+'s names set over it.
213
- # With +wait: true+, follows the deploy, under one idempotency key, until
214
- # it is live, failed or superseded, and returns it (check its state).
215
- def deploy(id, image: nil, build: nil, env: nil, keep_env: nil, port: nil, health_path: nil, wait: false,
216
- timeout: 300, poll: 0.25, idempotency_key: nil)
217
- unless image.nil? ^ build.nil?
218
- raise ArgumentError, "Deploy exactly one of image: or build:; nothing was sent."
219
- end
220
-
221
- body = Fields.body(image: image, build: build, env: env, keep_env: keep_env, port: port, health_path: health_path)
222
- write_deploy(id, "deploys", body, wait, timeout, poll, idempotency_key)
223
- end
224
-
225
- # A deploy, by the App's id and its own. With +wait_for:+ the API holds
226
- # the answer until that state or +timeout_seconds+ pass.
227
- def get_deploy(id, deploy_id, wait_for: nil, timeout_seconds: nil)
228
- read_deploy(id, deploy_id, wait_for, timeout_seconds, wait_for && ((timeout_seconds || 30) + 60))
229
- end
230
-
231
- # Resumes following a deploy by id after a restart, without making another version.
232
- def wait_deploy(id, deploy_id, timeout: 300, poll: 0.25)
233
- following(timeout, poll, nil) do |wait|
234
- follow_deploy(id, read_deploy(id, deploy_id, nil, nil, wait.left), wait)
235
- end
236
- end
237
-
238
- # Goes back to the previous version, as a new deploy; +wait: true+ as for +deploy+.
239
- def rollback(id, wait: false, timeout: 300, poll: 0.25, idempotency_key: nil)
240
- write_deploy(id, "rollback", {}, wait, timeout, poll, idempotency_key)
241
- end
242
-
243
- def versions(id) = @t.json("GET", "#{@base}/#{seg(id)}/versions").map { |version| Record.new(version) }
244
-
245
- def copies(id) = @t.json("GET", "#{@base}/#{seg(id)}/copies").map { |copy| Record.new(copy) }
246
-
247
- # What its copies printed: lines (at, Unix milliseconds; stream, stdout
248
- # or stderr; copy, a copy's id or nil; version or nil; text), oldest
249
- # first, the newest +limit:+ (1 to 500; 100) in the window, with
250
- # next_cursor and has_more. +since:+ is an RFC 3339 time or a duration
251
- # back from now ("30s", "15m", "2h", "7d"; "1h" by default; 14 days at
252
- # most). +version:+, +copy:+ and +stream:+ narrow it. Pass next_cursor as
253
- # +cursor:+, with the same filters, for the page of older lines.
254
- def logs(id, since: nil, version: nil, copy: nil, stream: nil, limit: nil, cursor: nil)
255
- Record.new(@t.json("GET", "#{@base}/#{seg(id)}/logs", query: log_query(since, version, copy, stream, limit, cursor)))
256
- end
257
-
258
- # Each event to the block as its copies print (or an Enumerator without
259
- # one), until the caller breaks out: a line (type "line", cursor, and a
260
- # line's fields as for +logs+) or a gap where the store dropped lines
261
- # (type "gap"); the stream goes on after it. A first follow sends the
262
- # newest +limit:+ lines since +since:+, then new ones; +cursor:+ resumes
263
- # after that line. Each follow the API ends after about two minutes is
264
- # resumed from its cursor; a lost connection reconnects from the last
265
- # line, up to three times in a row, then app_log_interrupted, whose details
266
- # cursor resumes. An error event raises its own code and hint.
267
- def follow_logs(id, since: nil, version: nil, copy: nil, stream: nil, limit: nil, cursor: nil, &block)
268
- unless block
269
- return enum_for(:follow_logs, id, since: since, version: version, copy: copy, stream: stream, limit: limit,
270
- cursor: cursor)
271
- end
272
-
273
- follow_lines(id, log_query(since, version, copy, stream, limit, nil), cursor, &block)
274
- nil
275
- end
276
-
277
- private
278
-
279
- def log_query(since, version, copy, stream, limit, cursor)
280
- { "since" => since, "version" => version, "copy" => copy, "stream" => stream, "limit" => limit, "cursor" => cursor }
281
- end
282
-
283
- def log_invalid(cursor) = failure("app_log_invalid", "Retry the log from the last received cursor.", cursor)
284
-
285
- def valid_log_line?(event)
286
- event["text"].is_a?(String) && %w[stdout stderr].include?(event["stream"]) && valid_cursor?(event["cursor"]) &&
287
- safe_integer?(event["at"]) && !event["at"].negative? && (event["copy"].nil? || event["copy"].is_a?(String)) &&
288
- (event["version"].nil? || safe_integer?(event["version"]))
289
- end
290
-
291
- # Cursors are opaque positions: they cannot be ordered or counted on, so
292
- # lines already given are known by their cursor.
293
- def follow_lines(id, filters, cursor)
294
- if cursor && !valid_cursor?(cursor)
295
- raise failure("invalid_log_options", "Use the opaque cursor of a line or a continue event to resume.", cursor)
296
- end
297
-
298
- seen = cursor ? { cursor => true } : {}
299
- failures = 0
300
- loop do
301
- continued = false
302
- begin
303
- # The API ends each follow after about two minutes, with a continue event.
304
- @t.events("GET", "#{@base}/#{seg(id)}/logs", query: { "follow" => true }.merge(filters, { "cursor" => cursor }),
305
- timeout: 180) do |event|
306
- raise log_invalid(cursor) unless event.is_a?(Hash)
307
-
308
- case event["type"]
309
- when "line"
310
- raise log_invalid(cursor) unless valid_log_line?(event)
311
- next if seen.key?(event["cursor"])
312
-
313
- seen[event["cursor"]] = true
314
- seen.delete(seen.first[0]) if seen.size > LOG_SEEN
315
- cursor = event["cursor"]
316
- failures = 0
317
- yield Record.new(event)
318
- when "gap"
319
- raise log_invalid(cursor) unless valid_cursor?(event["cursor"])
320
-
321
- cursor = event["cursor"]
322
- yield Record.new(event)
323
- when "continue"
324
- raise log_invalid(cursor) unless event["cursor"].nil? || valid_cursor?(event["cursor"])
325
-
326
- cursor = event["cursor"] || cursor
327
- continued = true
328
- break
329
- when "error"
330
- unless event["code"].is_a?(String) && !event["code"].empty? && event["hint"].is_a?(String) && !event["hint"].empty?
331
- raise log_invalid(cursor)
332
- end
333
-
334
- raise failure(event["code"], event["hint"], cursor)
335
- else
336
- raise log_invalid(cursor)
337
- end
338
- end
339
- rescue ConnectionError
340
- nil # A lost connection, not a refusal: the transport retries retryable answers. Reconnect from the last line.
341
- rescue Error => e
342
- raise e unless e.code == "unexpected_answer" && e.status.zero?
343
-
344
- raise failure("app_log_invalid", "The log contained invalid JSON; retry from details.cursor.", cursor)
345
- end
346
- failures += 1 unless continued
347
- if failures > LOG_RECONNECTS
348
- raise failure("app_log_interrupted", "Reconnect with follow_logs(id, cursor: details[\"cursor\"]).", cursor)
349
- end
350
-
351
- # A service that is down, or continuations one after another, never busy-loop.
352
- sleep(0.05 * [1, failures].max)
353
- end
354
- end
355
-
356
- def read_deploy(id, deploy_id, wait_for, timeout_seconds, timeout)
357
- Record.new(@t.json("GET", "#{@base}/#{seg(id)}/deploys/#{seg(deploy_id)}",
358
- query: { "waitFor" => wait_for, "timeoutSeconds" => timeout_seconds }, timeout: timeout))
359
- end
360
-
361
- def follow_deploy(id, record, wait)
362
- until DEPLOY_ENDED.include?(record.state)
363
- record = read_deploy(id, record.id, "live", 60, wait.left)
364
- wait.pause unless DEPLOY_ENDED.include?(record.state)
365
- end
366
- record
367
- end
368
-
369
- def write_deploy(id, verb, body, wait, timeout, poll, idempotency_key)
370
- write = ->(key, left) { Record.new(@t.json("POST", "#{@base}/#{seg(id)}/#{verb}", body: body, key: key, timeout: left)) }
371
- return write.call(idempotency_key, nil) unless wait
372
-
373
- key = idempotency_key || SecureRandom.uuid
374
- following(timeout, poll, key) { |follow| follow_deploy(id, write.call(key, follow.left), follow) }
375
- end
376
- end
377
- end
@@ -1,104 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module WithRuntime
4
- # +runtime.browsers+: a task in plain words, done by an agent that browses
5
- # in a sandbox with Chromium, at /v1/browsers/runs. In a private beta: an
6
- # account outside it is refused with product_in_beta (403,
7
- # PermissionDeniedError).
8
- #
9
- # run = runtime.browsers.run("Find the price of the cheapest plan on withruntime.com")
10
- # puts run.output || run.error
11
- # runtime.browsers.runs.follow(run.id) { |step| puts "#{step.n} #{step.url}" }
12
- #
13
- # The model's key is your egress secret: ANTHROPIC_API_KEY for claude-
14
- # models (the default, claude-sonnet-5-5), OPENAI_API_KEY for gpt- and
15
- # o-series, GEMINI_API_KEY for gemini-. A run is billed as its sandbox's
16
- # time, at the sandbox rates; the model's use is on your key.
17
- #
18
- # A run: id, state (queued, running, done, failed or stopped), task, model,
19
- # start_url, output (the answer, once done), error (why it failed, and what
20
- # to do), steps, url (the page it ended on), sandbox_id, labels,
21
- # created_at, started_at and ended_at. A step: n (0 is the page before the
22
- # first step; the last, the page at the end), url, title, goal, actions,
23
- # frame (the page as a base64 JPEG), at and seq.
24
- class Browsers < Product
25
- attr_reader :runs
26
-
27
- def initialize(transport)
28
- super
29
- @runs = BrowserRuns.new(transport)
30
- end
31
-
32
- # Does +task+ in a browser and returns the run once it has ended: +output+
33
- # once done, +error+ once failed. Also +start_url:+, +model:+,
34
- # +max_steps:+, +allowed_domains:+ and +labels:+.
35
- def run(task, **fields)
36
- @runs.wait(@runs.create(task, **fields).id)
37
- end
38
- end
39
-
40
- # +runtime.browsers.runs+: start, read, follow and stop runs.
41
- class BrowserRuns < Product
42
- ENDED = %w[done failed stopped].freeze
43
- # How long the API holds a steps read open, and the margin past it a
44
- # read waits for its answer.
45
- POLL_SECONDS = 30
46
- POLL_MARGIN = 15
47
-
48
- # Starts a run and returns it at once (state queued). +start_url:+ is
49
- # opened before the first step; +max_steps:+ is 1 to 200 (30 unless
50
- # set); +allowed_domains:+ limits the pages it opens.
51
- def create(task, start_url: nil, model: nil, max_steps: nil, allowed_domains: nil, labels: nil, idempotency_key: nil)
52
- body = Fields.body(task: task, start_url: start_url, model: model, max_steps: max_steps,
53
- allowed_domains: allowed_domains, labels: labels)
54
- Record.new(@t.json("POST", "/v1/browsers/runs", body: body, key: idempotency_key))
55
- end
56
-
57
- def get(id) = Record.new(@t.json("GET", path(id)))
58
-
59
- # The first page of runs, newest first; +each+ walks every page.
60
- def list(cursor: nil, limit: nil)
61
- body = @t.json("GET", "/v1/browsers/runs", query: { "cursor" => cursor, "limit" => limit })
62
- Page.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"]) { |after| list(cursor: after, limit: limit) }
63
- end
64
-
65
- # One page of its steps after seq +after+: {data, after, ended}. +wait:+
66
- # (seconds, up to 30) holds the answer on the server for a step.
67
- def steps(id, after: 0, limit: nil, frames: nil, wait: nil)
68
- query = { "after" => after, "limit" => limit, "frames" => frames, "wait" => wait }
69
- timeout = wait ? [@t.timeout, wait + POLL_MARGIN].max : nil
70
- @t.json("GET", path(id, "/steps"), query: query, timeout: timeout)
71
- end
72
-
73
- # Each step as it comes, until the run ends: its recording. Without a
74
- # block, an Enumerator. Each read waits on the server, not a timer.
75
- def follow(id, after: 0, frames: true, &block)
76
- return enum_for(:follow, id, after: after, frames: frames) unless block
77
-
78
- loop do
79
- page = steps(id, after: after, frames: frames ? nil : false, wait: POLL_SECONDS)
80
- data = page["data"] || []
81
- data.each { |step| yield Record.new(step) }
82
- after = page["after"] || after
83
- return nil if page["ended"] && data.empty?
84
- end
85
- end
86
-
87
- # Stops it; its sandbox is deleted and its steps are kept.
88
- def stop(id) = Record.new(@t.json("POST", path(id, ":stop"), body: {}))
89
-
90
- # The run once it has ended (done, failed or stopped); a failed run is
91
- # returned, not raised: read +error+.
92
- def wait(id)
93
- run = get(id)
94
- return run if ENDED.include?(run.state)
95
-
96
- follow(id, frames: false) { |_step| nil }
97
- get(id)
98
- end
99
-
100
- private
101
-
102
- def path(id, suffix = "") = "/v1/browsers/runs/#{seg(id)}#{suffix}"
103
- end
104
- end