withruntime 0.9.0 → 0.17.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.
@@ -23,9 +23,9 @@ module WithRuntime
23
23
  RENAME_RETIRES = nil
24
24
 
25
25
  class Client
26
- attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :limits, :emails, :referrals,
26
+ attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :reservations, :limits, :emails, :referrals, :plans,
27
27
  :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp, :agents,
28
- :apps, :functions, :builds, :containers
28
+ :apps, :functions, :builds, :ci, :containers
29
29
 
30
30
  # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
31
31
  # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
@@ -56,9 +56,11 @@ module WithRuntime
56
56
  @images = Images.new(@transport)
57
57
  @volumes = Volumes.new(@transport)
58
58
  @secrets = Secrets.new(@transport)
59
+ @reservations = Reservations.new(@transport)
59
60
  @limits = Limits.new(@transport)
60
61
  @emails = Emails.new(@transport)
61
62
  @referrals = Referrals.new(@transport)
63
+ @plans = Plans.new(@transport)
62
64
  @switching = Switching.new(@transport)
63
65
  @events = Events.new(@transport)
64
66
  @webhooks = Webhooks.new(@transport)
@@ -77,6 +79,7 @@ module WithRuntime
77
79
  @apps = Apps.new(@transport, "/v1/apps")
78
80
  @functions = Apps.new(@transport, "/v1/functions")
79
81
  @builds = Builds.new(@transport)
82
+ @ci = CI.new(@transport)
80
83
  @containers = Containers.new(@transport)
81
84
  end
82
85
 
@@ -93,6 +96,20 @@ module WithRuntime
93
96
  # The account's credit, holds, free time and per-resource charges.
94
97
  def usage = Record.new(@transport.json("GET", "/v1/usage"))
95
98
 
99
+ # One page of settled usage for every product the key sees: settled at
100
+ # +since+ or later and before +until+ (UTC, ending in Z). Follow
101
+ # +next_cursor+ with the same range until it is nil; concatenate each
102
+ # page's +csv+ (the header is on the first only). Money and quantities are
103
+ # exact decimal strings. +final_through+: no row settled before it can
104
+ # still appear or change, so the range is final once it reaches +until+.
105
+ # A row's +final+ is true once its resource is deleted and can be charged
106
+ # nothing more.
107
+ def usage_export(since:, until:, cursor: nil, limit: nil)
108
+ # until is a Ruby keyword: its argument is read through the binding.
109
+ query = { "since" => since, "until" => binding.local_variable_get(:until), "cursor" => cursor, "limit" => limit }
110
+ Record.new(@transport.json("GET", "/v1/usage/export", query: query))
111
+ end
112
+
96
113
  # Calls any API path with this client's key, retries, idempotency keys and
97
114
  # errors, and returns the parsed JSON answer. For an endpoint newer than this SDK.
98
115
  def request(method, path, query: nil, body: nil)
@@ -6,22 +6,33 @@ module WithRuntime
6
6
  # subclasses name the class of failure, as in the JavaScript, Python, Go and
7
7
  # Java SDKs.
8
8
  class Error < StandardError
9
- # 503s that are a deliberate state, not a passing one: retrying cannot change them.
9
+ # Products switched off on this deployment (501; 503 from an older
10
+ # server): a deliberate state, not a passing one, so retrying cannot
11
+ # change them. Read only when the answer carries no +retryable+.
10
12
  DELIBERATE = %w[
11
- unavailable unsupported fork_unavailable previews_unavailable
13
+ unavailable unsupported fork_unavailable previews_unavailable file_links_unavailable
12
14
  network_unavailable network_rules_unavailable secrets_unavailable identity_unavailable env_unavailable
13
- resize_unavailable
15
+ resize_unavailable feature_unavailable delete_unavailable switch_image_unavailable switching_paused
16
+ schema_migration_required storage_unavailable
14
17
  ].freeze
15
18
  # Refusals that pass on their own: a host frees room, a sandbox of an
16
19
  # account without credit stops.
17
20
  PASSING = %w[no_capacity no_credit_running_limit no_credit_total_limit].freeze
18
21
  # Refusals of a create that clear when a sandbox stops or a host frees room.
19
22
  WAITS_FOR_ROOM = %w[no_credit_running_limit no_credit_total_limit no_credit_domain_limit no_credit_capacity_full quota_exceeded no_capacity volume_releasing].freeze
23
+ # Refusals that say nothing ran (a guest still busy, the API briefly
24
+ # busy, the caller's rate): sent again past max_retries, with growing
25
+ # waits, until the call's deadline.
26
+ NOTHING_RAN = %w[guest_busy busy rate_limited].freeze
20
27
 
21
- attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after
28
+ attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after,
29
+ :retryable
22
30
 
23
- def initialize(message, code:, status: 0, hint: nil, request_id: nil, details: nil, idempotency_key: nil, retry_after: nil)
31
+ def initialize(message, code:, status: 0, hint: nil, request_id: nil, details: nil, idempotency_key: nil,
32
+ retry_after: nil, retryable: nil)
24
33
  super(message)
34
+ # The server's own word (true or false), or nil from an older server.
35
+ @retryable = [true, false].include?(retryable) ? retryable : nil
25
36
  @code = code
26
37
  @status = status
27
38
  @hint = hint
@@ -31,11 +42,23 @@ module WithRuntime
31
42
  @retry_after = retry_after
32
43
  end
33
44
 
34
- # Whether retrying this exact call, with the same idempotency key, is safe and may work.
45
+ # The answer's own +retryable+, or nil when it sent none (an older server).
46
+ def sent_retryable
47
+ @retryable
48
+ end
49
+
50
+ # Whether retrying this exact call, with the same idempotency key, is safe
51
+ # and may work: the server's +retryable+ when it sent one, else worked out
52
+ # from the code and status as older servers need.
35
53
  def retryable?
54
+ return @retryable unless @retryable.nil?
36
55
  return false if DELIBERATE.include?(code)
37
56
  return details["field"] != "count" if PASSING.include?(code)
38
57
 
58
+ # The account at one of its limits (a 429): some free when its own work ends,
59
+ # some only when something is deleted, so the same call again is no answer by itself.
60
+ return false if code == "quota_exceeded"
61
+
39
62
  [0, 429, 502, 503, 504].include?(status)
40
63
  end
41
64
 
@@ -67,7 +90,8 @@ module WithRuntime
67
90
  request_id: error["requestId"],
68
91
  details: error["details"].is_a?(Hash) ? error["details"] : nil,
69
92
  idempotency_key: idempotency_key,
70
- retry_after: retry_ms.is_a?(Numeric) ? retry_ms / 1000.0 : nil
93
+ retry_after: retry_ms.is_a?(Numeric) ? retry_ms / 1000.0 : nil,
94
+ retryable: error["retryable"]
71
95
  )
72
96
  end
73
97
 
@@ -5,6 +5,8 @@ require "openssl"
5
5
  module WithRuntime
6
6
  # The pieces every product shares.
7
7
  class Product
8
+ SAFE_INTEGER = (2**53) - 1
9
+
8
10
  def initialize(transport)
9
11
  @t = transport
10
12
  end
@@ -13,6 +15,16 @@ module WithRuntime
13
15
 
14
16
  def seg(value) = Transport.segment(value)
15
17
 
18
+ # A followed log's refusal, with the cursor it resumes from in its details.
19
+ def failure(code, hint, cursor) = Error.new(hint, code: code, hint: hint, details: { "cursor" => cursor })
20
+
21
+ # A log cursor is opaque: a short string with no control characters.
22
+ def valid_cursor?(value)
23
+ value.is_a?(String) && !value.empty? && value.length <= 4096 && !value.match?(/[\x00-\x1f\x7f]/)
24
+ end
25
+
26
+ def safe_integer?(value) = value.is_a?(Integer) && value.abs <= SAFE_INTEGER
27
+
16
28
  # A change's body from keyword arguments: nil is left out, +:remove+ sends
17
29
  # null, which clears the field.
18
30
  def patch(changes)
@@ -69,7 +81,20 @@ module WithRuntime
69
81
  def backup(id, name: nil, labels: nil, retention_days: nil, wait: 60, idempotency_key: nil)
70
82
  Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:backup", body: Fields.body(name: name, labels: labels, retention_days: retention_days), wait: wait, key: idempotency_key))
71
83
  end
72
- def set_backup_policy(id, daily: nil, retention_days: nil) = Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:backup-policy", body: Fields.body(daily: daily, retention_days: retention_days)))
84
+ # Automatic backups on or off and the days a daily one is kept; or a
85
+ # schedule of the volume's own: every_minutes (15 or more) or a five-field
86
+ # UTC cron, keeping the keep counts (last, hourly, daily, weekly, monthly,
87
+ # yearly). no_schedule: true goes back to daily backups.
88
+ def set_backup_policy(id, daily: nil, retention_days: nil, every_minutes: nil, cron: nil, keep: nil, no_schedule: false)
89
+ raise ArgumentError, "Give one of every_minutes, cron and no_schedule." if [every_minutes, cron, (no_schedule || nil)].compact.size > 1
90
+
91
+ body = Fields.body(daily: daily, retention_days: retention_days, keep: keep)
92
+ if every_minutes then body["schedule"] = { "everyMinutes" => every_minutes }
93
+ elsif cron then body["schedule"] = { "cron" => cron }
94
+ elsif no_schedule then body["schedule"] = nil
95
+ end
96
+ Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:backup-policy", body: body))
97
+ end
73
98
  def backups(volume_id: nil, state: nil, limit: nil) = page("/v1/volume-backups", { "volumeId" => volume_id, "state" => state, "limit" => limit })
74
99
  def get_backup(id) = Record.new(@t.json("GET", "/v1/volume-backups/#{seg(id)}"))
75
100
  def delete_backup(id) = Record.new(@t.json("POST", "/v1/volume-backups/#{seg(id)}:delete", body: {}))
@@ -96,13 +121,28 @@ module WithRuntime
96
121
  class Secrets < Product
97
122
  # Stores or replaces a secret for +hosts+ ("api.openai.com", "*.github.com").
98
123
  # With +header:+, that header is set on every request to them, +format:+'s
99
- # {value} replaced. With +only:+ (<tt>{ labels: [{ role: "hub" }], sandboxes: [id] }</tt>),
100
- # only those sandboxes get it instead of every sandbox of the organization: those whose
101
- # labels hold every pair of any one selector, and those named by id. Left out when replacing
102
- # a secret, the scope it has stays, so a new value never widens who gets it; +{}+ is every
103
- # sandbox again.
104
- def set(name, value:, hosts:, header: nil, format: nil, only: nil)
105
- body = { "value" => value, "hosts" => hosts, "header" => header, "format" => format, "only" => only }.compact
124
+ # {value} replaced.
125
+ #
126
+ # +rules:+ limits the value to the requests a rule allows, such as
127
+ # [{ "methods" => ["GET"], "paths" => ["/repos/acme/*"] }]. +only:+ gives it to
128
+ # those sandboxes alone ({ "labels" => [{ "role" => "hub" }], "sandboxes" => [ids],
129
+ # "apps" => [App ids] }; left out when replacing, the scope it has stays; {} is every
130
+ # sandbox again). +github_app:+ ({ "id" =>, "installation" =>,
131
+ # "repositories" =>, "permissions" =>, "api" => }) makes +value+ a GitHub App's
132
+ # private key (PEM); the servers make its installation tokens themselves, and the
133
+ # secret takes no +header:+ or +format:+. +git:+ ({ "push" => [branch patterns] };
134
+ # an empty list is no push at all) limits what a git push may update. +api:+
135
+ # ({ "callsPerHour" =>, "writesPerHour" =>, "keep" =>, "copies" =>, "fresh" =>,
136
+ # "graphql" => { "path" =>, "mutations" => [] } }) sets each sandbox's hour with the
137
+ # secret, the far end's reserve, GraphQL's mutations and shared copies. The answer
138
+ # and +list+ return them as +githubApp+, +git+ and +api+. +env:+ is the environment
139
+ # variable sandboxes see it in, when not the secret's name. Secrets scoped to different
140
+ # sandboxes may share one, such as one GITHUB_TOKEN per repository; a write that would
141
+ # put two in one sandbox is refused (409). Absent when replacing: the variable it has stays.
142
+ def set(name, value:, hosts:, header: nil, format: nil, rules: nil, only: nil, github_app: nil, git: nil,
143
+ api: nil, env: nil)
144
+ body = { "value" => value, "hosts" => hosts, "header" => header, "format" => format, "rules" => rules,
145
+ "only" => only, "githubApp" => github_app, "git" => git, "api" => api, "env" => env }.compact
106
146
  Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}", body: body))
107
147
  end
108
148
 
@@ -119,8 +159,20 @@ module WithRuntime
119
159
  Record.new(@t.json("PUT", "/v1/egress-secrets/#{seg(name)}/rules", body: body))
120
160
  end
121
161
 
122
- # Names, hosts and placeholders. Never values.
123
- def list = @t.json("GET", "/v1/egress-secrets")["secrets"].map { |secret| Record.new(secret) }
162
+ # Names, hosts and placeholders. Never values. With +limit:+ (1 to 100)
163
+ # or +after:+, one page by name: the secrets named after +after+; the next
164
+ # page's +after+ is this one's last name. Without, every secret.
165
+ def list(limit: nil, after: nil)
166
+ secrets = []
167
+ start = after
168
+ loop do
169
+ page = @t.json("GET", "/v1/egress-secrets", query: { "limit" => limit, "after" => start })
170
+ secrets.concat(page["secrets"].map { |secret| Record.new(secret) })
171
+ return secrets if limit || after || !page["next"]
172
+
173
+ start = page["next"]
174
+ end
175
+ end
124
176
 
125
177
  # Erases a secret; its placeholder stops working.
126
178
  def delete(name)
@@ -155,6 +207,52 @@ module WithRuntime
155
207
  end
156
208
  end
157
209
 
210
+ # +runtime.plans+: monthly plans whose fee is prepaid usage. The fee comes back as plan usage, spent first
211
+ # each month at the same measured prices, plus a bonus for committing; plan usage left at the period's end
212
+ # ends with it. Money is integer microdollars in strings.
213
+ #
214
+ # Every change answers +checkout_url+ (where a person starts a first plan or a trial in the browser, nil
215
+ # once the change was made) and +current+ (the plan as it is now). Each takes an +idempotency_key+; one is
216
+ # made per call when left out.
217
+ class Plans < Product
218
+ # +current+ (the plan you hold, or nil: plan_id, name, status, interval, period_start, period_end,
219
+ # trial_ends_at, cancel_at_period_end, next_plan_id, started_at, add_ons, auto_upgrade, plan_usage) and
220
+ # +plans+ (every plan you may choose: id, name, card, fee_micros, yearly_fee_micros, bonus_micros,
221
+ # trial_days, first_period_double, support, collection, contract, position, included, limits, features,
222
+ # add_ons).
223
+ def list = Record.new(@t.json("GET", "/v1/plans"))
224
+
225
+ # Start a plan, or move to another. With no plan, answers +checkout_url+. A dearer plan starts at once,
226
+ # prorated; a cheaper one at +period_end+ (+next_plan_id+). +interval: "year"+ pays ten months for
227
+ # twelve; monthly unless asked.
228
+ def choose(plan, interval: nil, idempotency_key: nil)
229
+ body = { "plan" => plan }
230
+ body["interval"] = interval unless interval.nil?
231
+ Record.new(@t.json("POST", "/v1/plans/choose", body: body, key: idempotency_key))
232
+ end
233
+
234
+ # End the plan at +period_end+.
235
+ def cancel(idempotency_key: nil) = Record.new(@t.json("POST", "/v1/plans/cancel", body: {}, key: idempotency_key))
236
+
237
+ # Keep a plan you cancelled, before +period_end+.
238
+ def resume(idempotency_key: nil) = Record.new(@t.json("POST", "/v1/plans/resume", body: {}, key: idempotency_key))
239
+
240
+ # Add an add-on by id: charged now for the rest of the period, prorated, then with the plan.
241
+ def add_on(id, idempotency_key: nil)
242
+ Record.new(@t.json("POST", "/v1/plans/add-ons", body: { "addOn" => id }, key: idempotency_key))
243
+ end
244
+
245
+ # Remove an add-on: its charge stops now, and it holds to +period_end+.
246
+ def remove_add_on(id, idempotency_key: nil)
247
+ Record.new(@t.json("DELETE", "/v1/plans/add-ons/#{seg(id)}", key: idempotency_key))
248
+ end
249
+
250
+ # Move up a plan by itself when a limit refuses (true), or not. Owners, and keys an owner made.
251
+ def auto_upgrade(on, idempotency_key: nil)
252
+ Record.new(@t.json("PUT", "/v1/plans/auto-upgrade", body: { "on" => on }, key: idempotency_key))
253
+ end
254
+ end
255
+
158
256
  # +runtime.switching+: compare usage with a rival's published rates, and record a switch.
159
257
  class Switching < Product
160
258
  # Your settled usage over the last +days+ (30 by default, at most 90) priced
@@ -304,7 +402,8 @@ module WithRuntime
304
402
 
305
403
  # Replaces the rules: +internet:+, +allow:+ (example.com, *.example.com, an
306
404
  # address or a CIDR range), +deny:+, and +connect:+ (host:port pairs beyond
307
- # 80 and 443; paid accounts only).
405
+ # 80 and 443; paid accounts only). +internet: false+ with +allow:+ is
406
+ # allow-list only, stored as +internet: true+ with that list.
308
407
  def set(internet:, allow: nil, deny: nil, connect: nil)
309
408
  body = { "internet" => internet, "allow" => allow, "deny" => deny, "connect" => connect }.compact
310
409
  Record.new(@sandbox.transport.json("PUT", @sandbox.path("/network"), body: body))
@@ -47,6 +47,17 @@ module WithRuntime
47
47
  end
48
48
  end
49
49
 
50
+ # The files a traced command (+trace_files: true+) opened: +read+ is every
51
+ # file and directory it, and anything it started, opened (sorted absolute
52
+ # paths with links resolved, directories ending in "/"); +written+ every file
53
+ # it wrote. +truncated+ means some paths are missing, so do not treat the
54
+ # lists as complete.
55
+ class TracedFiles < Record
56
+ def read = self["read"] || []
57
+ def written = self["written"] || []
58
+ def truncated = self["truncated"] == true
59
+ end
60
+
50
61
  # A finished command. A timeout is a result (+timed_out+), not an exception.
51
62
  class CommandResult < Record
52
63
  def exit_code = self["exitCode"]
@@ -54,6 +65,9 @@ module WithRuntime
54
65
  def stderr = self["stderr"] || ""
55
66
  def timed_out = self["timedOut"] == true
56
67
  def ok? = !timed_out && exit_code == 0
68
+
69
+ # The files it read and wrote when it ran with +trace_files: true+; nil otherwise.
70
+ def files = self["files"] && TracedFiles.new(self["files"])
57
71
  end
58
72
 
59
73
  # One page of a list. +next_page+ reads the one after it; +each+ walks every
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "time"
4
+
5
+ module WithRuntime
6
+ # +runtime.reservations+: book room for a burst. Holds room for +sandboxes+
7
+ # sandboxes of one size for a window (up to 24 hours, starting within 14 days)
8
+ # and answers at once, confirmed or declined. A decline is a normal answer
9
+ # (+status+ is "declined"; +reason+, +message+, +largest_sandboxes+ and
10
+ # +nearest_window+ say why and what would fit), not an error. In the window,
11
+ # creates are never refused no_capacity or quota_exceeded up to what you
12
+ # booked; running sandboxes are billed as usual and booked room none of your
13
+ # sandboxes use costs a quarter of the memory rate. +estimate_micros+ (the most
14
+ # it can cost: every sandbox running the whole window), +unused_rate_micros+
15
+ # (unused room per GiB-hour of memory, as quoted when booked),
16
+ # +unused_max_micros+ (the most it costs if none run) and
17
+ # +unused_charged_micros+ (charged so far) are microdollars as a string.
18
+ #
19
+ # booking = runtime.reservations.create(sandboxes: 500, starts_at: Time.now + 3600, ends_at: Time.now + 3 * 3600)
20
+ # booking.status # => "confirmed"
21
+ #
22
+ # Standing room (+keep+) is held from now until you cancel it, for a pool that
23
+ # deletes a sandbox after each use and makes another: a replacement is never
24
+ # refused up to it. With +snapshots+ it is held on the servers holding them,
25
+ # at their size; +for_key+ keeps it for this key's sandboxes alone. Its
26
+ # +ends_at+, +held_until+ and +unused_max_micros+ are nil;
27
+ # +unused_per_hour_micros+ is the most its unused room costs an hour.
28
+ #
29
+ # pool = runtime.reservations.keep(sandboxes: 40, snapshots: [snapshot_id], for_key: true)
30
+ class Reservations < Product
31
+ # +starts_at+ and +ends_at+ are a Time or an ISO 8601 string. +vcpu+,
32
+ # +memory_mib+, +disk_mib+ and +region+ default to a create's defaults
33
+ # (2 vCPU, 4096 MiB each, the default region).
34
+ def create(sandboxes:, starts_at:, ends_at:, vcpu: nil, memory_mib: nil, disk_mib: nil, region: nil, idempotency_key: nil)
35
+ body = Fields.body(sandboxes: sandboxes, starts_at: iso(starts_at), ends_at: iso(ends_at),
36
+ vcpu: vcpu, memory_mib: memory_mib, disk_mib: disk_mib, region: region)
37
+ Record.new(@t.json("POST", "/v1/reservations", body: body, key: idempotency_key))
38
+ end
39
+
40
+ # Keeps standing room for +sandboxes+ sandboxes until it is cancelled. Keep
41
+ # a few more than the pool runs, for deletes still finishing.
42
+ def keep(sandboxes:, snapshots: nil, for_key: nil, vcpu: nil, memory_mib: nil, disk_mib: nil, region: nil,
43
+ idempotency_key: nil)
44
+ body = Fields.body(standing: true, sandboxes: sandboxes, snapshots: snapshots, for_key: for_key || nil,
45
+ vcpu: vcpu, memory_mib: memory_mib, disk_mib: disk_mib, region: region)
46
+ Record.new(@t.json("POST", "/v1/reservations", body: body, key: idempotency_key))
47
+ end
48
+
49
+ # Changes standing room in place: how many it holds, its snapshots, or
50
+ # both. It moves or grows only when all of it fits now; otherwise it raises
51
+ # no_capacity and nothing changes.
52
+ def update(id, sandboxes: nil, snapshots: nil, idempotency_key: nil)
53
+ body = Fields.body(sandboxes: sandboxes, snapshots: snapshots)
54
+ Record.new(@t.json("POST", "/v1/reservations/#{seg(id)}:update", body: body, key: idempotency_key))
55
+ end
56
+
57
+ # Bookings, newest first, as a Page (+data+, +next_cursor+, +more?+,
58
+ # +next_page+); iterating it walks every page.
59
+ def list(limit: nil, cursor: nil)
60
+ query = { "limit" => limit, "cursor" => cursor }
61
+ body = @t.json("GET", "/v1/reservations", query: query)
62
+ Page.new(body["items"].map { |item| Record.new(item) }, body["nextCursor"]) do |next_cursor|
63
+ list(limit: limit, cursor: next_cursor)
64
+ end
65
+ end
66
+
67
+ def get(id) = Record.new(@t.json("GET", "/v1/reservations/#{seg(id)}"))
68
+
69
+ # Gives the room back. The booking comes back with status "cancelled".
70
+ def cancel(id) = Record.new(@t.json("DELETE", "/v1/reservations/#{seg(id)}"))
71
+
72
+ private
73
+
74
+ def iso(at) = at.respond_to?(:iso8601) ? at.iso8601(3) : at
75
+ end
76
+ end
@@ -165,7 +165,7 @@ module WithRuntime
165
165
  # limit so that +margin+ seconds remain, never more than the hour ahead the
166
166
  # API allows. A sandbox with no time limit needs none and is only watched.
167
167
  # Running time is billed as it is used. A paused sandbox is left paused; a
168
- # stopped one ends the loop.
168
+ # stopped or deleted one ends the loop.
169
169
  def keep_alive(every: 60, margin: ApiDefaults::KEEP_ALIVE_MARGIN_SECONDS, &on_error)
170
170
  stop_keep_alive
171
171
  every = [10, every].max
@@ -182,6 +182,10 @@ module WithRuntime
182
182
  extend_lease([3600, need].min) if need >= 1
183
183
  end
184
184
  rescue Error => e
185
+ # Gone (deleted elsewhere, or by its own time limit): nothing to
186
+ # keep alive, and asking again would only be refused.
187
+ break if e.status == 404
188
+
185
189
  on_error&.call(e)
186
190
  end
187
191
  sleep(every)
@@ -210,8 +214,8 @@ module WithRuntime
210
214
  end
211
215
 
212
216
  # Starts copies of this sandbox as it is now (files, memory, running
213
- # processes), each its own sandbox, on the same server, answered once they
214
- # run. One copy without +count+; an array with it. If a copy fails, the
217
+ # processes), each its own sandbox, on its server while it has room and on
218
+ # another when it is full, answered once they run. One copy without +count+; an array with it. If a copy fails, the
215
219
  # error's +details["startedSandboxIds"]+ names the copies that did start.
216
220
  # +funding+ is accepted and ignored: copies run on free usage first, then credit.
217
221
  # +secrets: [name, ...]+ is the egress secrets the copies may use, by name:
@@ -222,7 +226,8 @@ module WithRuntime
222
226
  idempotency_key: nil)
223
227
  body = Fields.body(count: count, name: name, labels: labels, keep_snapshot: keep_snapshot,
224
228
  secrets: secrets&.to_a)
225
- reply = @t.json("POST", path(":fork"), body: body, wait: 60, key: idempotency_key)
229
+ # Its key replays a refusal for room or a limit, so it is told at once.
230
+ reply = @t.json("POST", path(":fork"), body: body, wait: 60, key: idempotency_key, room: 0)
226
231
  copies = reply["sandboxes"].map { |info| Sandbox.new(@t, info) }
227
232
  count.nil? ? copies.first : copies
228
233
  end
@@ -258,15 +263,17 @@ module WithRuntime
258
263
  # sandbox's; put secrets here), +stdin+, +timeout+ (seconds, default 60, up
259
264
  # to a day; a timeout is a result, not an error), +on_stdout+ and
260
265
  # +on_stderr+ (stream the command; the result keeps everything), and
261
- # +check+ (raise CommandError on a non-zero exit or a timeout).
266
+ # +check+ (raise CommandError on a non-zero exit or a timeout), and
267
+ # +trace_files+ (the result's +files+ are the files it read and wrote; an
268
+ # older sandbox says to stop and start it, and no command runs).
262
269
  def exec(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
263
- check: false, idempotency_key: nil)
270
+ check: false, idempotency_key: nil, trace_files: false)
264
271
  streamed = on_stdout || on_stderr || (timeout && timeout > 60)
265
272
  result = if streamed
266
273
  collect(exec_stream(command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
267
- idempotency_key: idempotency_key), on_stdout, on_stderr)
274
+ idempotency_key: idempotency_key, trace_files: trace_files), on_stdout, on_stderr)
268
275
  else
269
- body = command_body(command, cwd, env, stdin, timeout, user)
276
+ body = command_body(command, cwd, env, stdin, timeout, user, trace_files)
270
277
  CommandResult.new(@t.json("POST", path(":exec"), body: body, key: idempotency_key,
271
278
  timeout: timeout && (timeout + 60)))
272
279
  end
@@ -278,14 +285,14 @@ module WithRuntime
278
285
  # Runs a command and yields its events as they happen: start, stdout,
279
286
  # stderr, exit (each a Hash). Resumes by itself when the server ends a long
280
287
  # stream, so it never drops output. Without a block, an Enumerator.
281
- def exec_stream(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, &block)
288
+ def exec_stream(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, trace_files: false, &block)
282
289
  unless block
283
290
  return enum_for(:exec_stream, command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
284
- idempotency_key: idempotency_key)
291
+ idempotency_key: idempotency_key, trace_files: trace_files)
285
292
  end
286
293
 
287
294
  longest = ApiDefaults::STREAMED_EXEC_TIMEOUT_SECONDS
288
- body = command_body(command, cwd, env, stdin, timeout || longest, user).merge("stream" => true)
295
+ body = command_body(command, cwd, env, stdin, timeout || longest, user, trace_files).merge("stream" => true)
289
296
  handed_over = nil
290
297
  process_id = nil
291
298
  cursor = 0
@@ -373,9 +380,11 @@ module WithRuntime
373
380
  # Starts a background process (a server, a watcher, a REPL) and returns at
374
381
  # once. It outlives your connection; +process(id)+ gets it back.
375
382
  # +pipe_stdin: true+ keeps input open for +write+; +pty: { cols:, rows: }+
376
- # gives it a terminal.
377
- def spawn(command, cwd: nil, user: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil, idempotency_key: nil)
378
- body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout, user)
383
+ # gives it a terminal; +trace_files: true+ records the files it opens, read
384
+ # them with +files+ once it has ended.
385
+ def spawn(command, cwd: nil, user: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil,
386
+ idempotency_key: nil, trace_files: false)
387
+ body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout, user, trace_files)
379
388
  body["stdinMode"] = "pipe" if pipe_stdin
380
389
  body["pty"] = Fields.body(pty) if pty
381
390
  SandboxProcess.new(self, @t.json("POST", path("/processes"), body: body, key: idempotency_key))
@@ -391,20 +400,21 @@ module WithRuntime
391
400
 
392
401
  private
393
402
 
394
- def lifecycle(verb, body, wait, key, room: 0)
403
+ def lifecycle(verb, body, wait, key, room: nil)
395
404
  @info = Record.new(@t.json("POST", path(":#{verb}"), body: body, wait: wait ? 60 : 0, key: key, room: room))
396
405
  self
397
406
  end
398
407
 
399
408
  def room_for(wait_for_capacity) = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
400
409
 
401
- def command_body(command, cwd, env, stdin, timeout, user)
410
+ def command_body(command, cwd, env, stdin, timeout, user, trace_files = false)
402
411
  body = command.is_a?(Array) ? { "argv" => command.map(&:to_s) } : { "command" => command.to_s }
403
412
  body["cwd"] = cwd if cwd
404
413
  body["user"] = user.to_s if user
405
414
  body["env"] = env.to_h { |key, value| [key.to_s, value.to_s] } if env
406
415
  body["stdinBase64"] = [stdin.to_s.b].pack("m0") unless stdin.nil?
407
416
  body["timeoutMs"] = (timeout * 1000).round if timeout
417
+ body["traceFiles"] = true if trace_files
408
418
  body
409
419
  end
410
420
 
@@ -423,7 +433,7 @@ module WithRuntime
423
433
  stderr << event["data"]
424
434
  on_stderr&.call(event["data"])
425
435
  when "truncated" then dropped = true
426
- when "exit" then fields.merge!(event.slice("exitCode", "timedOut", "durationMs"))
436
+ when "exit" then fields.merge!(event.slice("exitCode", "timedOut", "durationMs", "files"))
427
437
  end
428
438
  end
429
439
  # A truncated event does not say which stream lost bytes, so both flags carry it.
@@ -495,6 +505,10 @@ module WithRuntime
495
505
  # Changes a PTY process's terminal size.
496
506
  def resize(cols, rows) = @sandbox.transport.json("POST", path(":resize"), body: { "cols" => cols, "rows" => rows })
497
507
 
508
+ # The files a process spawned with +trace_files: true+ read and wrote. Fails
509
+ # with process_running while it runs.
510
+ def files = TracedFiles.new(@sandbox.transport.json("GET", path("/files")))
511
+
498
512
  # Reads the process again.
499
513
  def refresh
500
514
  @info = Record.new(@sandbox.transport.json("GET", path))
@@ -630,6 +644,28 @@ module WithRuntime
630
644
  nil
631
645
  end
632
646
 
647
+ # A link anyone can open with no API key to download +path+ (a Hash with
648
+ # "url" and "expiresAt"). Range works. It lasts an hour by default, at most
649
+ # 7 days (+expires_in_seconds+). +filename+ saves it under that name;
650
+ # +wake+ true wakes a paused sandbox, false never does; +archive+ links a
651
+ # folder as a .tar.gz.
652
+ def download_url(path, expires_in_seconds: nil, filename: nil, wake: nil, archive: nil)
653
+ body = { "path" => path, "method" => "GET", "expiresInSeconds" => expires_in_seconds,
654
+ "filename" => filename, "wake" => wake, "archive" => archive }.compact
655
+ t.json("POST", @sandbox.path("/files:link"), body: body)
656
+ end
657
+
658
+ # A link anyone can PUT a raw body to with no API key: the body becomes the
659
+ # file at +path+, whole or not at all, up to +max_bytes+ (5 GiB at most).
660
+ def upload_url(path, expires_in_seconds: nil, max_bytes: nil, wake: nil)
661
+ body = { "path" => path, "method" => "PUT", "expiresInSeconds" => expires_in_seconds,
662
+ "maxBytes" => max_bytes, "wake" => wake }.compact
663
+ t.json("POST", @sandbox.path("/files:link"), body: body)
664
+ end
665
+
666
+ # Ends every link made for this sandbox so far.
667
+ def revoke_links = t.json("POST", @sandbox.path("/files:revoke-links"))
668
+
633
669
  # Copies a local file or directory in. A directory travels as one gzipped
634
670
  # tar to the API's folder routes, unpacked by the sandbox's own tar as it
635
671
  # arrives.