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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dcc3df961b7af1a6f8c2941b1e829ce2e7b4f0e1dfcc8a57a5b32159c89996e7
4
- data.tar.gz: e664bcedb285f6edda1adc3e5fd05fc5a4bd2b304e2e8d64d5dd46420128984f
3
+ metadata.gz: 1c1a17e5090c78b095eebfac78fff07cbd5222b14ba973cc71c619fec9ed4722
4
+ data.tar.gz: ee609373f8a0c8dbfb12ede50c25930647456031fef41576d411a60e5743dfbb
5
5
  SHA512:
6
- metadata.gz: 28da69ad5124df7ff53dc9b2ce0d17b7bd3e9ef934512884433bfe1aea3fa0983b259ec5dc2ea50f2f9c138e19e8d296221ef6b895115762c13e5a69ef082d63
7
- data.tar.gz: 5d468e2f92368d91bea955b684fffc05f8be9404aa54c3dae3434baa1e3882de718416ce341ea26a30a49966cf416d5f986a188ade46888971315018afc2ebf0
6
+ metadata.gz: f4ecd87a36108a2a1856e9e0051d010bdeae9393e5ada0681264d6bf81758afdabd33b3f4148e08a08ca94eb5018d718c2601bbf9f2cc1b7972a4b95886534d2
7
+ data.tar.gz: 555018e2954343260c2f88f6661d800ce8ecbd482f91acfdfe7c5f2e9b96ecd8880dfb2a16ace2c65264fd9d3311a361f398ab3637a257effd1d521e74b0062b
@@ -59,28 +59,34 @@ module WithRuntime
59
59
  # session.events.each { |event| puts event.text if event.kind == "reply" }
60
60
  #
61
61
  # A definition is a Hash, by snake_case keyword (+memory_mib:+) or by the
62
- # API's own key ("memoryMiB"): +command+ (required), +from+ ({ image: } or
63
- # { snapshot: }), +vcpu+ and +memory_mib+ (4 vCPU and 8 GiB unless set; a
62
+ # API's own key ("memoryMiB"): +command+ (required), +from+ ({ image: },
63
+ # { snapshot: }, or { repo: "owner/name" }: a repository connected to
64
+ # CI/CD, each session a copy of its warm snapshot, checked out at
65
+ # /workspace/repo), +vcpu+ and +memory_mib+ (4 vCPU and 8 GiB unless set; a
64
66
  # definition from a snapshot takes neither, InvalidRequestError, since a
65
67
  # snapshot keeps its own size), +instructions+, +env+, +secrets+ (names of
66
- # egress secrets: model keys go here), +mcp+ ([{ name:, url: }]), +volumes+
68
+ # egress secrets: model keys go here), +pool+ (1 to 16 Claude accounts,
69
+ # each an egress secret's name: each session takes the one with the most
70
+ # usage left, and the review template moves to the next when one is out
71
+ # of usage), +mcp+ ([{ name:, url: }]), +volumes+
67
72
  # ([{ volume:, path: }]), +idle_pause_seconds+, +max_session_seconds+,
68
73
  # +max_concurrent+, +max_session_dollars+ (more than 0, at most 10000, 5
69
74
  # unless set: the session and every session under it, the root's covering
70
75
  # its tree; a tree at it stops, reason "budget"), +max_day_dollars+ (more
71
76
  # than 0, at most 100000, 100 unless set: the agent's sessions started that
72
- # UTC day; an agent at it starts nothing new, ConflictError
73
- # +budget_reached+, until the next day) and +template+ ("support" or
77
+ # UTC day; an agent at it starts nothing new, +budget_reached+
78
+ # (402), until the next day) and +template+ ("support" or
74
79
  # "team").
75
80
  class Agents < Product
76
- attr_reader :sessions, :triggers, :templates
81
+ attr_reader :sessions, :triggers, :templates, :memory, :asks
77
82
 
78
83
  def initialize(transport)
79
84
  super
80
85
  @sessions = AgentSessions.new(transport)
81
86
  @triggers = AgentTriggers.new(transport)
82
87
  @templates = AgentTemplates.new
83
- # Approvals come later, here: agents.approvals.list / answer.
88
+ @memory = AgentMemory.new(transport)
89
+ @asks = AgentAsks.new(transport)
84
90
  end
85
91
 
86
92
  # Makes an agent at version 1. A name already used is a ConflictError
@@ -111,7 +117,7 @@ module WithRuntime
111
117
  # name for the conversation (a Slack thread, a pull request, one of your
112
118
  # customers such as "customer:42"), words with the same key join the open
113
119
  # session instead of starting a second; +session.joined+ says so. An agent
114
- # at its day's budget is refused +budget_reached+ (ConflictError).
120
+ # at its day's budget is refused +budget_reached+ (402).
115
121
  def start(agent, input, key: nil, labels: nil, idempotency_key: nil)
116
122
  body = Fields.body(input: input, key: key, labels: labels)
117
123
  answer = @t.json("POST", "/v1/agents/#{seg(agent)}/sessions", body: body, key: idempotency_key)
@@ -294,26 +300,175 @@ module WithRuntime
294
300
  #
295
301
  # A slack or github trigger whose app is not installed for the account is
296
302
  # refused +not_installed+ (ConflictError).
303
+ #
304
+ # Each trigger has +rules+, every one optional: +priority+ (-100 to 100:
305
+ # queue order when the agent's maxConcurrent is full, higher first),
306
+ # +max_starts_per_hour+ (a call past it is held for you), +on_ended+
307
+ # ("start", "note" or "ask": what a call does when its key's session has
308
+ # ended), +notify+ ("email" or "webhook": where a held call is told) and,
309
+ # a webhook's only, +key+ ("{cause}": the key of a call that sends none,
310
+ # from its JSON's fields). A call no session can take is held, never
311
+ # dropped: +held+, +start_held+, +dismiss_held+.
297
312
  class AgentTriggers < Product
298
- def create(agent, kind, config = {})
299
- Record.new(@t.json("POST", "/v1/agents/#{seg(agent)}/triggers", body: { "kind" => kind, "config" => Fields.convert(config.to_h) }))
313
+ def create(agent, kind, config = {}, rules: nil)
314
+ body = { "kind" => kind, "config" => Fields.convert(config.to_h) }
315
+ body["rules"] = Fields.convert(rules.to_h) if rules
316
+ Record.new(@t.json("POST", "/v1/agents/#{seg(agent)}/triggers", body: body))
317
+ end
318
+
319
+ # Its rules, whole, in place: its secret stays. +{}+ is every default.
320
+ def set_rules(id, rules)
321
+ Record.new(@t.json("PATCH", "/v1/agents/triggers/#{seg(id)}", body: { "rules" => Fields.convert(rules.to_h) }))
322
+ end
323
+
324
+ # Calls a webhook trigger as its sender would, by its +secret+, never your
325
+ # key: +outcome+ started, joined (the open session with +key+), noted or
326
+ # held, with +session_id+, +seq+, +call_id+ and +why+. The same
327
+ # +idempotency_key+ is the same call.
328
+ def call(id, secret, text, key: nil, labels: nil, idempotency_key: nil)
329
+ body = Fields.body(text: text, key: key, labels: labels)
330
+ Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/calls", body: body, bearer: secret,
331
+ key: idempotency_key))
332
+ end
333
+
334
+ # The calls it held for you, newest first; +each+ walks every page.
335
+ def held(id, state: nil, cursor: nil, limit: nil)
336
+ held_page(id, { "state" => state, "limit" => limit }, cursor)
337
+ end
338
+
339
+ # Starts a held call: one session with it and every call held for its key
340
+ # since, oldest first. +session+, +joined+ and +calls+.
341
+ def start_held(id, call_id)
342
+ Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/held/#{seg(call_id)}/start", body: {}))
343
+ end
344
+
345
+ # Dismisses a held call: nothing runs.
346
+ def dismiss_held(id, call_id)
347
+ Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/held/#{seg(call_id)}/dismiss", body: {}))
300
348
  end
301
349
 
302
350
  def list(agent) = @t.json("GET", "/v1/agents/#{seg(agent)}/triggers")["data"].map { |row| Record.new(row) }
303
351
 
304
- # Holds this trigger alone; its events are refused +trigger_paused+, with
305
- # +why+, where they came from. Nothing else is held.
352
+ # Holds this trigger alone, saying +why+: a webhook's calls are held for
353
+ # you (+held+), never dropped. Nothing else is held.
306
354
  def pause(id, why) = Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/pause", body: { "why" => why }))
307
355
 
308
356
  def resume(id) = Record.new(@t.json("POST", "/v1/agents/triggers/#{seg(id)}/resume", body: {}))
309
357
 
310
358
  def delete(id) = @t.json("DELETE", "/v1/agents/triggers/#{seg(id)}") && nil
359
+
360
+ private
361
+
362
+ def held_page(id, query, cursor)
363
+ body = @t.json("GET", "/v1/agents/triggers/#{seg(id)}/held", query: query.merge("cursor" => cursor))
364
+ Page.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"]) { |after| held_page(id, query, after) }
365
+ end
366
+ end
367
+
368
+ # +runtime.agents.asks+: the account's inbox, the questions its agents'
369
+ # sessions need answered to go on. Each has +why+ it matters, +options+
370
+ # ({label, detail}), a recommended +pick+ and maybe an expiry. Asks of
371
+ # one agent's sessions sharing a memory, with the same +step+, are one
372
+ # row while it is open, and one answer reaches every session asking. +state+: open, answered,
373
+ # withdrawn, expired (no pick) or closed (every asking session ended).
374
+ class AgentAsks < Product
375
+ # The first page, newest first: open asks unless +state+ (one or a list)
376
+ # says otherwise; of one +agent+; carrying every one of +labels+ (who sees
377
+ # an ask). +each+ walks every page.
378
+ def list(state: nil, agent: nil, labels: nil, cursor: nil, limit: nil)
379
+ label = labels&.map { |k, v| "#{k}:#{v}" }
380
+ asks_page({ "state" => state, "agent" => agent, "label" => label, "limit" => limit }, cursor)
381
+ end
382
+
383
+ # One ask, with the sessions asking it.
384
+ def get(id) = Record.new(@t.json("GET", "/v1/agents/asks/#{seg(id)}"))
385
+
386
+ # Answers with an +option+'s label, +text+, or both: every session asking
387
+ # reads it next and wakes. One no longer open is refused +ask_closed+
388
+ # (ConflictError).
389
+ def answer(id, option = nil, text: nil, idempotency_key: nil)
390
+ raise ArgumentError, "an answer is an option's label, text, or both" if option.nil? && text.nil?
391
+
392
+ body = Fields.body(option: option, text: text)
393
+ Record.new(@t.json("POST", "/v1/agents/asks/#{seg(id)}/answer", body: body, key: idempotency_key))
394
+ end
395
+
396
+ private
397
+
398
+ def asks_page(query, cursor)
399
+ body = @t.json("GET", "/v1/agents/asks", query: query.merge("cursor" => cursor))
400
+ Page.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"]) { |after| asks_page(query, after) }
401
+ end
402
+ end
403
+
404
+ # A page of an agent's memory files; +usage+ is the agent's whole memory,
405
+ # every scope: +bytes+, +files+, +limit_bytes+ and +limit_files+.
406
+ class AgentMemoryPage < Page
407
+ attr_reader :usage
408
+
409
+ def initialize(data, next_cursor, usage, &fetch)
410
+ super(data, next_cursor, &fetch)
411
+ @usage = usage
412
+ end
311
413
  end
312
414
 
313
- # +runtime.agents.templates+: the five harnesses an agent can run, each
314
- # usable for either use, and the two uses.
415
+ # +runtime.agents.memory+: an agent's built-in memory, text files its
416
+ # sessions keep across sessions and search. A +scope+ is whose: "" (the
417
+ # default) for what every session of the agent shares, or a session key such
418
+ # as "customer:42" for that key's alone. Up to 1 MiB a file, 1 GiB and
419
+ # 100,000 files an agent, billed as storage; past them a write is refused
420
+ # +memory_full+ (ConflictError).
315
421
  #
316
- # runtime.agents.templates.map(&:key) # claude-code, codex, gemini-cli, claude-agent-sdk, openai-agents-sdk
422
+ # runtime.agents.memory.write("helpdesk", "faq/refunds.md", "Refunds within 30 days.")
423
+ # runtime.agents.memory.search("helpdesk", "refund").each { |hit| puts "#{hit.path}: #{hit.snippet}" }
424
+ class AgentMemory < Product
425
+ # The first page of an agent's files by scope and path, each with +scope+,
426
+ # +path+, +bytes+, +updated_at+ and +updated_by+; every scope unless
427
+ # +scope:+ is given. +each+ walks every page.
428
+ def list(agent, scope: nil, prefix: nil, cursor: nil, limit: nil)
429
+ memory_page(agent, { "scope" => scope, "prefix" => prefix, "limit" => limit }, cursor)
430
+ end
431
+
432
+ # The files whose words or path match +q+ (words, "a phrase", or, -not),
433
+ # best first, each with a +snippet+ and +rank+; every scope unless
434
+ # +scope:+ is given.
435
+ def search(agent, q, scope: nil, limit: nil)
436
+ body = @t.json("GET", "/v1/agents/#{seg(agent)}/memory", query: { "scope" => scope, "q" => q, "limit" => limit })
437
+ body["data"].map { |row| Record.new(row) }
438
+ end
439
+
440
+ # A file with its +content+; none there is NotFoundError.
441
+ def read(agent, path, scope: "")
442
+ Record.new(@t.json("GET", file(agent), query: { "scope" => scope, "path" => path }))
443
+ end
444
+
445
+ # Seeds or replaces a file; +created+ says which.
446
+ def write(agent, path, content, scope: "")
447
+ Record.new(@t.json("PUT", file(agent), query: { "scope" => scope, "path" => path }, body: { "content" => content }))
448
+ end
449
+
450
+ # Deletes a file; whether there was one.
451
+ def delete(agent, path, scope: "")
452
+ @t.json("DELETE", file(agent), query: { "scope" => scope, "path" => path })["deleted"] == true
453
+ end
454
+
455
+ private
456
+
457
+ def file(agent) = "/v1/agents/#{seg(agent)}/memory/content"
458
+
459
+ def memory_page(agent, query, cursor)
460
+ body = @t.json("GET", "/v1/agents/#{seg(agent)}/memory", query: query.merge("cursor" => cursor))
461
+ AgentMemoryPage.new(body["data"].map { |item| Record.new(item) }, body["nextCursor"], Record.new(body["usage"] || {})) do |after|
462
+ memory_page(agent, query, after)
463
+ end
464
+ end
465
+ end
466
+
467
+ # +runtime.agents.templates+: the harnesses an agent can run, each usable
468
+ # for either use, and the two uses. +review+ is a CI/CD agent step's
469
+ # reviewer, on a +pool+ of Claude accounts.
470
+ #
471
+ # runtime.agents.templates.map(&:key) # claude-code, codex, gemini-cli, claude-agent-sdk, openai-agents-sdk, review, judge
317
472
  # runtime.agents.templates["codex"].api_key_secret
318
473
  # runtime.agents.templates.uses["support"].session_key
319
474
  # runtime.agents.templates.definition("claude-code", use: "support")
@@ -388,6 +543,36 @@ module WithRuntime
388
543
  "command" => "python3 ~/agent.py",
389
544
  "secrets" => ["OPENAI_API_KEY"]
390
545
  }
546
+ },
547
+ "review" => {
548
+ "key" => "review",
549
+ "title" => "Code review",
550
+ "command" => "python3 ~/.runtime-agent/runtime-agent review",
551
+ "apiKeySecret" => "ANTHROPIC_API_KEY",
552
+ "apiKeyHost" => "api.anthropic.com",
553
+ "subscription" => "a token per account: run `claude setup-token` on your own computer (Pro/Max) for each, store each with `runtime secrets set CLAUDE_1` scoped to api.anthropic.com, then name them all in pool (--pool CLAUDE_1 --pool CLAUDE_2)",
554
+ "definition" => {
555
+ "command" => "python3 ~/.runtime-agent/runtime-agent review",
556
+ "pool" => ["ANTHROPIC_API_KEY"],
557
+ "vcpu" => 2,
558
+ "memoryMiB" => 2048,
559
+ "maxSessionSeconds" => 1800
560
+ }
561
+ },
562
+ "judge" => {
563
+ "key" => "judge",
564
+ "title" => "Your rules",
565
+ "command" => "python3 ~/.runtime-agent/runtime-agent judge",
566
+ "apiKeySecret" => "ANTHROPIC_API_KEY",
567
+ "apiKeyHost" => "api.anthropic.com",
568
+ "subscription" => "a token per account, as for review: `runtime secrets set CLAUDE_1` scoped to api.anthropic.com for each, then name them all in pool; its instructions are the rules that block",
569
+ "definition" => {
570
+ "command" => "python3 ~/.runtime-agent/runtime-agent judge",
571
+ "pool" => ["ANTHROPIC_API_KEY"],
572
+ "vcpu" => 2,
573
+ "memoryMiB" => 2048,
574
+ "maxSessionSeconds" => 1800
575
+ }
391
576
  }
392
577
  },
393
578
  "uses" => {
@@ -151,20 +151,32 @@ module WithRuntime
151
151
  # deploy = runtime.apps.deploy(app.id, image: "web:latest", env: { "MODE" => "prod" }, wait: true)
152
152
  # puts deploy.url
153
153
  #
154
- # An App or Function: id, name, labels, state (waiting, live, failed,
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,
155
157
  # deleting, deleted), min_copies, max_copies, concurrency, spares, vcpu,
156
- # memory_mib, port, health_path, live_version, previous_version, error
157
- # ({code, message} or nil), created_at, updated_at, deleted_at, and
158
- # release_watch (rollback, alert or off) where the API sends it.
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).
159
167
  #
160
168
  # A deploy: id, version, url and state (building, warming, switching, live,
161
169
  # failed, superseded); a failed or superseded one has error with code
162
- # (deploy_build_failed, deploy_health_failed, deploy_superseded), message,
163
- # hint and last_output. A version: version, live, previous, saved, deploy
164
- # (its deploy's id) and build (nil for an image). A copy: id, version,
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,
165
174
  # region, state (starting, serving, draining, frozen, parked) and since.
166
175
  class Apps < ResourceProduct
167
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
168
180
 
169
181
  # +path+: /v1/apps or /v1/functions.
170
182
  def initialize(transport, path = "/v1/apps")
@@ -173,9 +185,21 @@ module WithRuntime
173
185
 
174
186
  # Creates one waiting for its first version: +max_copies:+ (1 to 1000),
175
187
  # +vcpu:+ (1 to 16) and +memory_mib:+ (128 to 65536) are required;
176
- # +concurrency:+, +spares:+, +port:+ (8080), +health_path:+, +name:+,
177
- # +labels:+, and for an App +min_copies:+ (0). A Function leaves
178
- # +min_copies+ out, zero included.
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.
179
203
  def create(idempotency_key: nil, **fields) = super
180
204
 
181
205
  # Follows resource state, not a deploy: an older live version can survive
@@ -220,8 +244,115 @@ module WithRuntime
220
244
 
221
245
  def copies(id) = @t.json("GET", "#{@base}/#{seg(id)}/copies").map { |copy| Record.new(copy) }
222
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
+
223
277
  private
224
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
+
225
356
  def read_deploy(id, deploy_id, wait_for, timeout_seconds, timeout)
226
357
  Record.new(@t.json("GET", "#{@base}/#{seg(id)}/deploys/#{seg(deploy_id)}",
227
358
  query: { "waitFor" => wait_for, "timeoutSeconds" => timeout_seconds }, timeout: timeout))
@@ -18,7 +18,6 @@ module WithRuntime
18
18
  # Reconnections in a row with no new line before a follow gives up.
19
19
  RECONNECTS = 3
20
20
  SEEN = 10_000
21
- SAFE_INTEGER = (2**53) - 1
22
21
 
23
22
  attr_reader :repositories
24
23
 
@@ -69,14 +68,8 @@ module WithRuntime
69
68
 
70
69
  def path(id) = "/v1/builds/#{seg(id)}"
71
70
 
72
- def failure(code, hint, cursor) = Error.new(hint, code: code, hint: hint, details: { "cursor" => cursor })
73
-
74
71
  def invalid(cursor) = failure("build_log_invalid", "Retry the log from the last received cursor.", cursor)
75
72
 
76
- def valid_cursor?(value)
77
- value.is_a?(String) && !value.empty? && value.length <= 4096 && !value.match?(/[\x00-\x1f\x7f]/)
78
- end
79
-
80
73
  def valid_failure?(value)
81
74
  return true if value.nil?
82
75
  return false unless value.is_a?(Hash)
@@ -86,8 +79,6 @@ module WithRuntime
86
79
  lines.is_a?(Array) && lines.size <= 20 && lines.all?(String)
87
80
  end
88
81
 
89
- def safe_integer?(value) = value.is_a?(Integer) && value.abs <= SAFE_INTEGER
90
-
91
82
  def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
92
83
 
93
84
  # Cursors are opaque physical positions: they cannot be ordered or
@@ -0,0 +1,156 @@
1
+ # frozen_string_literal: true
2
+
3
+ module WithRuntime
4
+ # +runtime.ci+: CI/CD. A connected repository's checks run as jobs in
5
+ # sandboxes. In a private beta: an account outside it is refused with
6
+ # product_in_beta (403, PermissionDeniedError). Times are Unix milliseconds.
7
+ #
8
+ # repo = runtime.ci.repositories.connect("acme/web")
9
+ # check = runtime.ci.checks.list(repository_id: repo.id, state: ["failed"]).first
10
+ # job = runtime.ci.checks.get(check.id).jobs.first
11
+ # puts runtime.ci.jobs.get(job.id).log
12
+ class CI < Product
13
+ attr_reader :repositories, :checks, :jobs, :tests, :flakes, :releases
14
+
15
+ def initialize(transport)
16
+ super
17
+ @repositories = CIRepositories.new(transport)
18
+ @checks = CIChecks.new(transport)
19
+ @jobs = CIJobs.new(transport)
20
+ @tests = CITests.new(transport)
21
+ @flakes = CIFlakes.new(transport)
22
+ @releases = CIReleases.new(transport)
23
+ end
24
+ end
25
+
26
+ # +runtime.ci.repositories+: the repositories whose checks run.
27
+ #
28
+ # A repository: id, name, labels, repository (owner/name), production_branch,
29
+ # config_path, installation, github_repository_id, undo_culprits (whether a
30
+ # red production branch's culprit is undone: set_undo), state (connected or
31
+ # disconnected), error, created_at, updated_at and deleted_at.
32
+ class CIRepositories < Product
33
+ # Connects +repository+ ("owner/name"), read through Runtime's GitHub App.
34
+ # Pushes and pull requests then run the checks written in +config_path:+
35
+ # (runtime.yml). Optional: production_branch (main), config_path,
36
+ # installation (the GitHub App installation to read it through; the newest
37
+ # when left out), name and labels.
38
+ def connect(repository, production_branch: nil, config_path: nil, installation: nil, name: nil, labels: nil,
39
+ idempotency_key: nil)
40
+ body = Fields.body(repository: repository, production_branch: production_branch, config_path: config_path,
41
+ installation: installation, name: name, labels: labels)
42
+ Record.new(@t.json("POST", "/v1/ci/repositories", body: body, key: idempotency_key))
43
+ end
44
+
45
+ # +label+ is "key:value" strings, +state+ connected or disconnected.
46
+ def list(name: nil, label: nil, state: nil, limit: nil, cursor: nil)
47
+ page("/v1/ci/repositories", { "name" => name, "label" => label, "state" => state, "limit" => limit, "cursor" => cursor })
48
+ end
49
+
50
+ # Turns on (or off) the undo of a red production branch's culprit: when
51
+ # main's check fails, CI/CD finds the first commit that fails it and opens
52
+ # a pull request reverting it, which lands once its own check passes. Off
53
+ # until set; only an owner's or admin's full key sets it.
54
+ def set_undo(id, on, idempotency_key: nil)
55
+ Record.new(@t.json("POST", "/v1/ci/repositories/#{seg(id)}:update", body: { "undoCulprits" => on },
56
+ key: idempotency_key))
57
+ end
58
+
59
+ # Stops running its checks; the checks already run stay readable.
60
+ def disconnect(id, idempotency_key: nil)
61
+ Record.new(@t.json("DELETE", "/v1/ci/repositories/#{seg(id)}", key: idempotency_key))
62
+ end
63
+ end
64
+
65
+ # +runtime.ci.checks+: one run of a commit's jobs.
66
+ #
67
+ # A check: id, repository_id, repository, commit, branch, event, pull_request,
68
+ # base_commit, actor, trusted, waiting, approved_by, approved_at, landed,
69
+ # state (queued, running, passed, failed or cancelled), reason, counts (jobs
70
+ # per state), machines (where its machines came from and how soon, or nil),
71
+ # created_at, updated_at, started_at and ended_at.
72
+ class CIChecks < Product
73
+ # Checks, newest first. +state+ is any of queued, running, passed, failed,
74
+ # cancelled; +commit+ is a full sha.
75
+ def list(repository_id: nil, state: nil, branch: nil, commit: nil, pull_request: nil, limit: nil, cursor: nil)
76
+ page("/v1/ci/checks", { "repositoryId" => repository_id, "state" => state, "branch" => branch, "commit" => commit,
77
+ "pullRequest" => pull_request, "limit" => limit, "cursor" => cursor })
78
+ end
79
+
80
+ # The check with its +jobs+ in plan order (no log).
81
+ def get(id) = Record.new(@t.json("GET", "/v1/ci/checks/#{seg(id)}"))
82
+
83
+ # Cancels a queued or running check: its jobs end and its machines are let
84
+ # go. A check that has ended is answered as it is.
85
+ def cancel(id) = Record.new(@t.json("POST", "/v1/ci/checks/#{seg(id)}:cancel"))
86
+
87
+ # Runs a check again, as GitHub's Re-run does: a new check of the same
88
+ # commit, trusted only as the commit's last check was.
89
+ def rerun(id) = Record.new(@t.json("POST", "/v1/ci/checks/#{seg(id)}:rerun"))
90
+ end
91
+
92
+ # +runtime.ci.jobs+: one command of a check, run in sandboxes.
93
+ class CIJobs < Product
94
+ # The job with its +log+ (the tail, at most 256 KiB). A failed job's
95
+ # sandbox_ids may be kept paused: wake one or exec in it with
96
+ # +runtime.sandboxes+. An agent step's job (+review:+ is its short form)
97
+ # has its +review+: the verdict (pass or block), summary, findings (kind,
98
+ # file, line, what, fix), notes, and the agent, the model the step asked
99
+ # for (nil when none) and the session that gave it; nil otherwise.
100
+ def get(id) = Record.new(@t.json("GET", "/v1/ci/jobs/#{seg(id)}"))
101
+ end
102
+
103
+ # +runtime.ci.tests+: a repository's test files and their recent runs.
104
+ class CITests < Product
105
+ # Test files by name: file, ms, quarantined_since (their failures do not
106
+ # fail a check), runs and updated_at.
107
+ def list(repository_id, quarantined: nil, limit: nil, cursor: nil)
108
+ page("/v1/ci/tests", { "repositoryId" => repository_id, "quarantined" => quarantined, "limit" => limit, "cursor" => cursor })
109
+ end
110
+ end
111
+
112
+ # +runtime.ci.flakes+: tests that passed and failed on the same inputs, one
113
+ # run main's. Each is quarantined at once (it still runs and reports, and
114
+ # blocks nothing), or still gating when the repository protects it; handed
115
+ # to an owner with 48 hours to fix it or delete it with a reason; fixed once
116
+ # 100 runs of a main commit in parallel forks all pass.
117
+ #
118
+ # A flake: id, repository_id, file, state (quarantined, gating, fixed or
119
+ # deleted), gates, proof, again, owner (login, from, pull_request, branch),
120
+ # since, due_at, overdue, tried, prove_asked_at, delete_reason, ended_at,
121
+ # ended_check_id and updated_at; with a get or an update, its runs and
122
+ # failures too.
123
+ class CIFlakes < Product
124
+ # Flaky tests, newest first. +state+ is any of quarantined, gating (the
125
+ # open ones), fixed, deleted.
126
+ def list(repository_id: nil, state: nil, limit: nil, cursor: nil)
127
+ page("/v1/ci/flakes", { "repositoryId" => repository_id, "state" => state, "limit" => limit, "cursor" => cursor })
128
+ end
129
+
130
+ # The flake with its test file's newest 200 +runs+ (by commit and content
131
+ # key) and its +failures+' jobs, whose logs +runtime.ci.jobs.get+ reads.
132
+ def get(id) = Record.new(@t.json("GET", "/v1/ci/flakes/#{seg(id)}"))
133
+
134
+ # +prove: true+ asks for its 100 proof runs at main's next commit; +owner:+
135
+ # hands it to a GitHub login or org/team; +delete_reason:+ says why its
136
+ # test is deleted (it ends once main no longer holds the file).
137
+ def update(id, prove: nil, owner: nil, delete_reason: nil, idempotency_key: nil)
138
+ body = Fields.body(prove: prove, owner: owner, delete_reason: delete_reason)
139
+ Record.new(@t.json("POST", "/v1/ci/flakes/#{seg(id)}:update", body: body, key: idempotency_key))
140
+ end
141
+ end
142
+
143
+ # +runtime.ci.releases+: the steps each release took, as it took them: a
144
+ # migration's copy test or apply, a deploy ref moved, a server's canary or
145
+ # release, the website's deploy or promote, or a wait and why. Only
146
+ # repositories whose releases CI/CD runs have any.
147
+ #
148
+ # A step: id, repository_id, commit, source (mover, or the deploy target
149
+ # that walked it), host (or nil), line and at.
150
+ class CIReleases < Product
151
+ # Steps, newest first; +commit:+ keeps one release's.
152
+ def list(repository_id: nil, commit: nil, limit: nil, cursor: nil)
153
+ page("/v1/ci/releases", { "repositoryId" => repository_id, "commit" => commit, "limit" => limit, "cursor" => cursor })
154
+ end
155
+ end
156
+ end