kloudlite-sdk 0.2.1 → 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.
- checksums.yaml +4 -4
- data/kloudlite.rb +55 -55
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: dd75a7d6e85fb97fe7f374fda5db6424a9b49d71d620ac9d630532d51faf292a
|
|
4
|
+
data.tar.gz: f1c0968d90ac15c46ba486558fc44348c7873b9a8672bb1cbeffd2c59a6d5198
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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:,
|
|
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
|
|
|
@@ -25,7 +25,7 @@ require "timeout"
|
|
|
25
25
|
require "uri"
|
|
26
26
|
|
|
27
27
|
module Kloudlite
|
|
28
|
-
VERSION = "0.2.
|
|
28
|
+
VERSION = "0.2.2"
|
|
29
29
|
USER_AGENT = "kloudlite-sdk-ruby/#{VERSION}".freeze
|
|
30
30
|
NO_LOGIN = "no Kloudlite login: pass token=, set KLOUDLITE_TOKEN, or run kloudlite login"
|
|
31
31
|
|
|
@@ -40,14 +40,14 @@ module Kloudlite
|
|
|
40
40
|
end
|
|
41
41
|
end
|
|
42
42
|
|
|
43
|
-
# A
|
|
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
|
|
45
|
+
class CapsuleTerminated < ApiError
|
|
46
46
|
attr_reader :reason
|
|
47
47
|
|
|
48
|
-
def initialize(
|
|
48
|
+
def initialize(capsule, reason, detail)
|
|
49
49
|
@reason = reason
|
|
50
|
-
text = "
|
|
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, :
|
|
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
|
-
@
|
|
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
|
-
#
|
|
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]});
|
|
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
|
|
570
|
-
# Same inputs as
|
|
571
|
-
def
|
|
572
|
-
|
|
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/
|
|
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
|
|
715
|
+
# 300). Every call answers a Capsule handle.
|
|
716
716
|
#
|
|
717
|
-
# sb = kl.
|
|
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
|
|
720
|
+
class Capsules
|
|
721
721
|
include Names
|
|
722
722
|
|
|
723
|
-
# The POST /v1/
|
|
724
|
-
# Sessions#
|
|
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
|
|
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
|
|
746
|
-
# Sessions#
|
|
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
|
-
|
|
748
|
+
Capsule.new(@c, @c.request("POST", "/v1/capsules", body: Capsules.body(cmd: cmd, **options)))
|
|
749
749
|
end
|
|
750
750
|
|
|
751
|
-
# One
|
|
752
|
-
def get(
|
|
753
|
-
|
|
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
|
|
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
|
-
# [
|
|
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/
|
|
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|
|
|
768
|
+
[(docs || []).map { |d| Capsule.new(@c, d) }, resp["X-Next-Cursor"]]
|
|
769
769
|
end
|
|
770
770
|
|
|
771
|
-
# One command in a fresh
|
|
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", "
|
|
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
|
|
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" => "", "
|
|
792
|
+
{ "exit_code" => code, "stdout" => out, "stderr" => "", "capsule" => sb.id }
|
|
793
793
|
end
|
|
794
794
|
end
|
|
795
795
|
|
|
796
|
-
# A handle on one
|
|
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
|
|
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
|
|
826
|
-
#
|
|
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
|
|
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
|
|
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/
|
|
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, "
|
|
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 && (
|
|
859
|
+
deadline = timeout_s && (Capsule.now + timeout_s)
|
|
860
860
|
loop do
|
|
861
|
-
left_ms = deadline ? ((deadline -
|
|
862
|
-
raise TimeoutError, "
|
|
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
|
|
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::
|
|
877
|
+
"#<Kloudlite::Capsule #{id} #{phase}#{reason ? " #{reason}" : ''}>"
|
|
878
878
|
end
|
|
879
879
|
|
|
880
880
|
private
|
|
881
881
|
|
|
882
882
|
def base
|
|
883
|
-
"/v1/
|
|
883
|
+
"/v1/capsules/#{seg(id)}"
|
|
884
884
|
end
|
|
885
885
|
|
|
886
886
|
def poll_until(timeout_s, what)
|
|
887
|
-
deadline = 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 -
|
|
893
|
-
raise TimeoutError, "
|
|
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
|
|
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), "
|
|
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
|
|
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.
|
|
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-
|
|
11
|
+
date: 2026-11-07 00:00:00.000000000 Z
|
|
12
12
|
dependencies: []
|
|
13
13
|
description:
|
|
14
14
|
email:
|