kloudlite-sdk 0.2.2 → 0.3.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 (3) hide show
  1. checksums.yaml +4 -4
  2. data/kloudlite.rb +54 -54
  3. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4347b7ccb1c4d71229743b41bb0c2f39c03d3f3bc6d7d87e73bc0bb80aac9ce1
4
- data.tar.gz: 14c3717a66d18c8287e09291a44e69e80c4bf6aeb569c77cb5cf49f9f9ba7257
3
+ metadata.gz: dd75a7d6e85fb97fe7f374fda5db6424a9b49d71d620ac9d630532d51faf292a
4
+ data.tar.gz: f1c0968d90ac15c46ba486558fc44348c7873b9a8672bb1cbeffd2c59a6d5198
5
5
  SHA512:
6
- metadata.gz: fd2a3e5d833b9cb9ac1e47d365cea0fa3f56cd0c4e3d2a05ec5fa957502b045c93b9650c0b158f44773f771c2eb2b15e6c3ed8c64a082078e566a9b7706f61a1
7
- data.tar.gz: 3b9e0d6ac8380763891f52c90ef3bd4527582c0815f18b9526cb854ad6ebe705d7525beb5fd12c07379c1ebf6adb8d63082793d30346e43b2733a6b75d2e51f3
6
+ metadata.gz: d5366f04c3488d12699d25b62dc3d2c97ed18144c6b78aaf9815393791a8b79c95997f8bcf82077bc8486fdb3c80f059242c4ca6bbad4894a3f18734ad8ba7b9
7
+ data.tar.gz: 91574f8a943ccdf59a555997ad0d50b656e861c78846eb9db4f55f0923b088164a3a846ea881f64115e04d2600dd86cee493be04b7269034972f70e5525c0c9b
data/kloudlite.rb CHANGED
@@ -15,7 +15,7 @@
15
15
  #
16
16
  # Every public method takes KEYWORD arguments, so no caller has to remember an order; a
17
17
  # resource is always the keyword named after it (workspace:, environment:, session:,
18
- # volume:, snapshot:, sandbox:, run:), and a new object made from an existing one is to:.
18
+ # volume:, snapshot:, capsule:, run:), and a new object made from an existing one is to:.
19
19
 
20
20
  raise LoadError, "kloudlite.rb needs Ruby 3.0 or later, found #{RUBY_VERSION}" if RUBY_VERSION < "3.0"
21
21
 
@@ -40,14 +40,14 @@ module Kloudlite
40
40
  end
41
41
  end
42
42
 
43
- # A sandbox that ended while the caller waited for it to run; +reason+ is the server's
43
+ # A capsule that ended while the caller waited for it to run; +reason+ is the server's
44
44
  # (Timeout, Idle, Unplaceable, …). An ApiError so one rescue covers both.
45
- class SandboxTerminated < ApiError
45
+ class CapsuleTerminated < ApiError
46
46
  attr_reader :reason
47
47
 
48
- def initialize(sandbox, reason, detail)
48
+ def initialize(capsule, reason, detail)
49
49
  @reason = reason
50
- text = "sandbox #{sandbox} is terminated (#{reason || 'unknown'})"
50
+ text = "capsule #{capsule} is terminated (#{reason || 'unknown'})"
51
51
  text += ": #{detail}" unless detail.nil? || detail.to_s.empty?
52
52
  super(409, text)
53
53
  end
@@ -79,7 +79,7 @@ module Kloudlite
79
79
 
80
80
  class Client
81
81
  attr_reader :workspaces, :environments, :sessions, :volumes,
82
- :secrets, :connectors, :sandboxes, :pipelines
82
+ :secrets, :connectors, :capsules, :pipelines
83
83
 
84
84
  def initialize(base_url: nil, token: nil, timeout: 30)
85
85
  base_url = presence(base_url) || presence(ENV["KLOUDLITE_URL"])
@@ -101,7 +101,7 @@ module Kloudlite
101
101
  @volumes = Volumes.new(self)
102
102
  @secrets = Secrets.new(self)
103
103
  @connectors = Connectors.new(self)
104
- @sandboxes = Sandboxes.new(self)
104
+ @capsules = Capsules.new(self)
105
105
  @pipelines = Pipelines.new(self)
106
106
  end
107
107
 
@@ -245,7 +245,7 @@ module Kloudlite
245
245
  end
246
246
 
247
247
  # Seconds unused before the workspace is deleted (600..=2592000); nil clears it. Not for a
248
- # sandbox or a bench.
248
+ # capsule or a bench.
249
249
  def set_ttl(workspace:, ttl_secs:)
250
250
  at("PUT", workspace, "/ttl", body: { ttl_secs: ttl_secs })
251
251
  end
@@ -547,7 +547,7 @@ module Kloudlite
547
547
  at("PUT", session, "/environment", body: { environment: environment })
548
548
  end
549
549
 
550
- # Stop the session and every workspace in it (202, {"stopped" => [ids]}); sandboxes and the
550
+ # Stop the session and every workspace in it (202, {"stopped" => [ids]}); capsules and the
551
551
  # environment are untouched.
552
552
  def stop(session:)
553
553
  at("POST", session, "/stop")
@@ -566,10 +566,10 @@ module Kloudlite
566
566
  at("DELETE", session, "/workspaces/#{seg(workspace)}")
567
567
  end
568
568
 
569
- # Create a sandbox managed by the session (202), in its team and reaching its environment.
570
- # Same inputs as Sandboxes#create (+team+ must be the session's).
571
- def create_sandbox(session:, cmd:, **options)
572
- Sandbox.new(@c, at("POST", session, "/sandboxes", body: Sandboxes.body(cmd: cmd, **options)))
569
+ # Create a capsule managed by the session (202), in its team and reaching its environment.
570
+ # Same inputs as Capsules#create (+team+ must be the session's).
571
+ def create_capsule(session:, cmd:, **options)
572
+ Capsule.new(@c, at("POST", session, "/capsules", body: Capsules.body(cmd: cmd, **options)))
573
573
  end
574
574
 
575
575
  # Send everything that calls +service+ in the environment to +workspace+ (a member), +ports+
@@ -709,19 +709,19 @@ module Kloudlite
709
709
  end
710
710
  end
711
711
 
712
- # Throwaway, isolated machines that run ONE command, over /v1/sandboxes. A sandbox starts from
712
+ # Throwaway, isolated machines that run ONE command, over /v1/capsules. A capsule starts from
713
713
  # an image, from one of your workspaces (+from_workspace+) or from a pushed snapshot
714
714
  # (+from_snapshot+), runs +cmd+, and ends when it exits or after +timeout_s+ (server default
715
- # 300). Every call answers a Sandbox handle.
715
+ # 300). Every call answers a Capsule handle.
716
716
  #
717
- # sb = kl.sandboxes.create(cmd: ["python3", "-c", "print(6 * 7)"], packages: ["python3"])
717
+ # sb = kl.capsules.create(cmd: ["python3", "-c", "print(6 * 7)"], packages: ["python3"])
718
718
  # code = sb.wait
719
719
  # puts code, sb.logs
720
- class Sandboxes
720
+ class Capsules
721
721
  include Names
722
722
 
723
- # The POST /v1/sandboxes body; refuses a missing +cmd+ before anything is sent. Shared with
724
- # Sessions#create_sandbox — not public surface.
723
+ # The POST /v1/capsules body; refuses a missing +cmd+ before anything is sent. Shared with
724
+ # Sessions#create_capsule — not public surface.
725
725
  def self.body(cmd:, image: nil, packages: nil, from_workspace: nil, from_snapshot: nil, team: nil,
726
726
  tty: nil, stdin: nil, timeout_s: nil, network: nil, env: nil, cpu: nil,
727
727
  memory_gb: nil, disk_gb: nil)
@@ -738,41 +738,41 @@ module Kloudlite
738
738
  @c = client
739
739
  end
740
740
 
741
- # Ask for a sandbox and return at once (202); it is usually still "pending". +cmd+ (required)
741
+ # Ask for a capsule and return at once (202); it is usually still "pending". +cmd+ (required)
742
742
  # is the program then its arguments. +tty+ runs it on a pty; +stdin+ keeps input open for
743
743
  # attach. +timeout_s+ is 10..=86400. +from_workspace+ is an id, "name" or "team/name";
744
744
  # +from_snapshot+ a volume name, "name@N" or snapshot id (exclusive with it). +network+ is
745
- # "internet" or "none"; +cpu+ 1..=8, +memory_gb+ 1..=32. A session's sandbox is made with
746
- # Sessions#create_sandbox. Unset keywords are omitted, so the server's defaults apply.
745
+ # "internet" or "none"; +cpu+ 1..=8, +memory_gb+ 1..=32. A session's capsule is made with
746
+ # Sessions#create_capsule. Unset keywords are omitted, so the server's defaults apply.
747
747
  def create(cmd:, **options)
748
- Sandbox.new(@c, @c.request("POST", "/v1/sandboxes", body: Sandboxes.body(cmd: cmd, **options)))
748
+ Capsule.new(@c, @c.request("POST", "/v1/capsules", body: Capsules.body(cmd: cmd, **options)))
749
749
  end
750
750
 
751
- # One sandbox by id (a name does not resolve).
752
- def get(sandbox:)
753
- Sandbox.new(@c, @c.request("GET", "/v1/sandboxes/#{seg(sandbox)}"))
751
+ # One capsule by id (a name does not resolve).
752
+ def get(capsule:)
753
+ Capsule.new(@c, @c.request("GET", "/v1/capsules/#{seg(capsule)}"))
754
754
  end
755
755
 
756
- # ONE page of the caller's sandboxes, newest first (+limit+ 1..=200, default 50); +team+
756
+ # ONE page of the caller's capsules, newest first (+limit+ 1..=200, default 50); +team+
757
757
  # scopes to that team. +list_page+ also answers the next cursor.
758
758
  def list(team: nil, limit: nil, cursor: nil)
759
759
  list_page(team: team, limit: limit, cursor: cursor).first
760
760
  end
761
761
 
762
- # [sandboxes, next_cursor]: a page, and the X-Next-Cursor to pass as +cursor+ for the next
762
+ # [capsules, next_cursor]: a page, and the X-Next-Cursor to pass as +cursor+ for the next
763
763
  # one (nil on the last page).
764
764
  def list_page(team: nil, limit: nil, cursor: nil)
765
- resp = @c.__send__(:perform, "GET", "/v1/sandboxes", nil,
765
+ resp = @c.__send__(:perform, "GET", "/v1/capsules", nil,
766
766
  { team: team, limit: limit, cursor: cursor }, "application/json", 30)
767
767
  docs = resp.body.to_s.empty? ? [] : JSON.parse(resp.body)
768
- [(docs || []).map { |d| Sandbox.new(@c, d) }, resp["X-Next-Cursor"]]
768
+ [(docs || []).map { |d| Capsule.new(@c, d) }, resp["X-Next-Cursor"]]
769
769
  end
770
770
 
771
- # One command in a fresh sandbox: create, wait for it to exit, read the output, and
771
+ # One command in a fresh capsule: create, wait for it to exit, read the output, and
772
772
  # terminate — ALWAYS, also when anything before it raised. Answers
773
- # {"exit_code", "stdout", "stderr", "sandbox"}: the sandbox keeps one stream, so "stdout"
773
+ # {"exit_code", "stdout", "stderr", "capsule"}: the capsule keeps one stream, so "stdout"
774
774
  # holds the output and error output together and "stderr" is "". +timeout_s+ bounds the wait
775
- # (TimeoutError; nil waits as long as it takes) and, when given, sizes the sandbox's own
775
+ # (TimeoutError; nil waits as long as it takes) and, when given, sizes the capsule's own
776
776
  # lifetime to cover it plus a minute. +options+ are the other keywords of +create+.
777
777
  def run(cmd:, timeout_s: nil, **options)
778
778
  options[:timeout_s] = (timeout_s.ceil + 60).clamp(10, 86_400) if timeout_s && !options.key?(:timeout_s)
@@ -789,14 +789,14 @@ module Kloudlite
789
789
  raise
790
790
  end
791
791
  sb.terminate
792
- { "exit_code" => code, "stdout" => out, "stderr" => "", "sandbox" => sb.id }
792
+ { "exit_code" => code, "stdout" => out, "stderr" => "", "capsule" => sb.id }
793
793
  end
794
794
  end
795
795
 
796
- # A handle on one sandbox: id, phase ("pending", "starting", "running", "terminated"), reason
796
+ # A handle on one capsule: id, phase ("pending", "starting", "running", "terminated"), reason
797
797
  # once terminated, exit_code, and the whole server doc as of the last answer — +refresh+
798
798
  # re-reads it. Fields read as sb["phase"] or through the named readers.
799
- class Sandbox
799
+ class Capsule
800
800
  include Names
801
801
 
802
802
  attr_reader :doc
@@ -822,27 +822,27 @@ module Kloudlite
822
822
  self
823
823
  end
824
824
 
825
- # Poll (0.5 s backing off to 2 s) until running. A sandbox that terminates first raises
826
- # SandboxTerminated naming the reason; +timeout_s+ passing raises TimeoutError.
825
+ # Poll (0.5 s backing off to 2 s) until running. A capsule that terminates first raises
826
+ # CapsuleTerminated naming the reason; +timeout_s+ passing raises TimeoutError.
827
827
  def wait_running(timeout_s: 120)
828
828
  poll_until(timeout_s, "running") do
829
- raise SandboxTerminated.new(id, reason, message) if phase == "terminated"
829
+ raise CapsuleTerminated.new(id, reason, message) if phase == "terminated"
830
830
  phase == "running"
831
831
  end
832
832
  end
833
833
 
834
834
  # The main process's output (stdout and stderr together) as text: the live output while it
835
- # runs, the last 256 KiB after. +follow+ holds until the process ends. 409 while the sandbox
835
+ # runs, the last 256 KiB after. +follow+ holds until the process ends. 409 while the capsule
836
836
  # has no output yet (still starting).
837
837
  def logs(follow: false)
838
838
  @c.__send__(:perform, "GET", "#{base}/logs", nil, { follow: follow ? "true" : nil },
839
839
  "text/plain", follow ? nil : 30).body.to_s.dup.force_encoding(Encoding::UTF_8).scrub
840
840
  end
841
841
 
842
- # Not in this SDK: GET /v1/sandboxes/{id}/attach is a WebSocket and this client uses only
842
+ # Not in this SDK: GET /v1/capsules/{id}/attach is a WebSocket and this client uses only
843
843
  # the standard library.
844
844
  def attach(cols: nil, rows: nil)
845
- raise NotImplementedError, "sandbox attach is a WebSocket and is not in the Ruby SDK"
845
+ raise NotImplementedError, "capsule attach is a WebSocket and is not in the Ruby SDK"
846
846
  end
847
847
 
848
848
  # Stop it for good (202, or 200 if already ended); the record stays until +delete+. Returns
@@ -856,10 +856,10 @@ module Kloudlite
856
856
  # the command exiting; +reason+ says how). Waits in steps of at most 20 s, the most the api
857
857
  # holds one open; TimeoutError past +timeout_s+.
858
858
  def wait(timeout_s: nil)
859
- deadline = timeout_s && (Sandbox.now + timeout_s)
859
+ deadline = timeout_s && (Capsule.now + timeout_s)
860
860
  loop do
861
- left_ms = deadline ? ((deadline - Sandbox.now) * 1000).to_i : 20_000
862
- raise TimeoutError, "sandbox #{id} still #{phase} after #{timeout_s} s" if left_ms <= 0
861
+ left_ms = deadline ? ((deadline - Capsule.now) * 1000).to_i : 20_000
862
+ raise TimeoutError, "capsule #{id} still #{phase} after #{timeout_s} s" if left_ms <= 0
863
863
 
864
864
  out = @c.request("POST", "#{base}/wait", body: { timeout_ms: [left_ms, 20_000].min }) || {}
865
865
  @doc = @doc.merge(out.slice("phase", "reason", "exit_code", "message"))
@@ -867,30 +867,30 @@ module Kloudlite
867
867
  end
868
868
  end
869
869
 
870
- # Delete the record (204); a sandbox still running dies with it.
870
+ # Delete the record (204); a capsule still running dies with it.
871
871
  def delete
872
872
  @c.request("DELETE", base)
873
873
  nil
874
874
  end
875
875
 
876
876
  def inspect
877
- "#<Kloudlite::Sandbox #{id} #{phase}#{reason ? " #{reason}" : ''}>"
877
+ "#<Kloudlite::Capsule #{id} #{phase}#{reason ? " #{reason}" : ''}>"
878
878
  end
879
879
 
880
880
  private
881
881
 
882
882
  def base
883
- "/v1/sandboxes/#{seg(id)}"
883
+ "/v1/capsules/#{seg(id)}"
884
884
  end
885
885
 
886
886
  def poll_until(timeout_s, what)
887
- deadline = timeout_s && (Sandbox.now + timeout_s)
887
+ deadline = timeout_s && (Capsule.now + timeout_s)
888
888
  delay = 0.5
889
889
  loop do
890
890
  refresh
891
891
  return self if yield
892
- left = deadline && (deadline - Sandbox.now)
893
- raise TimeoutError, "sandbox #{id} was not #{what} within #{timeout_s}s (phase #{phase})" if left && left <= 0
892
+ left = deadline && (deadline - Capsule.now)
893
+ raise TimeoutError, "capsule #{id} was not #{what} within #{timeout_s}s (phase #{phase})" if left && left <= 0
894
894
  sleep(left ? [delay, left].min : delay)
895
895
  delay = [delay * 2, 2.0].min
896
896
  end
@@ -903,7 +903,7 @@ module Kloudlite
903
903
  end
904
904
 
905
905
  # Pipelines, over /v1/pipelines: a JSON definition stored as numbered versions; a run executes
906
- # one version, each job in its own sandbox. +run+, +runs+ and +get_run+ answer Run handles.
906
+ # one version, each job in its own capsule. +run+, +runs+ and +get_run+ answer Run handles.
907
907
  #
908
908
  # kl.pipelines.create(owner: "acme", definition: definition)
909
909
  # run = kl.pipelines.run(owner: "acme", pipeline: "test", inputs: { "target" => "staging" })
@@ -988,7 +988,7 @@ module Kloudlite
988
988
  # One pipeline run: the doc the server last answered (camelCase, as the wire spells it), plus
989
989
  # the verbs. Fields read as run["state"] or through the named readers; +state+ is queued,
990
990
  # running, success, failure or cancelled. Each of +jobs+ is a Hash with "key", "job", "matrix",
991
- # "needs", "state" (pending, running, success, failure, skipped, cancelled), "sandbox",
991
+ # "needs", "state" (pending, running, success, failure, skipped, cancelled), "capsule",
992
992
  # "startedAtMs", "finishedAtMs", "exitCode", "failedStep" and "detail"; +logs+ and +follow+
993
993
  # name one by its index or its "key".
994
994
  class Run
@@ -1032,7 +1032,7 @@ module Kloudlite
1032
1032
  end
1033
1033
 
1034
1034
  # Ask it to stop: a queued run is cancelled at once, a running one once its worker has ended
1035
- # its sandboxes — +wait+ sees it reach cancelled. Returns self with the answered doc.
1035
+ # its capsules — +wait+ sees it reach cancelled. Returns self with the answered doc.
1036
1036
  def cancel
1037
1037
  @doc = @c.request("POST", "#{base}/cancel") || @doc
1038
1038
  self
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: kloudlite-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.2
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kloudlite
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-26 00:00:00.000000000 Z
11
+ date: 2026-11-07 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description:
14
14
  email: