kloudlite-sdk 0.3.0 → 0.5.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 +107 -70
  3. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dd75a7d6e85fb97fe7f374fda5db6424a9b49d71d620ac9d630532d51faf292a
4
- data.tar.gz: f1c0968d90ac15c46ba486558fc44348c7873b9a8672bb1cbeffd2c59a6d5198
3
+ metadata.gz: f3cc583a7ea00949b98460f9f2a3eac30312baee4f1c98c29a9f9f7db9008615
4
+ data.tar.gz: b728e4a16fcb7100d37feea60d4d742a9637e38488ebb92c9650bd545b5738e4
5
5
  SHA512:
6
- metadata.gz: d5366f04c3488d12699d25b62dc3d2c97ed18144c6b78aaf9815393791a8b79c95997f8bcf82077bc8486fdb3c80f059242c4ca6bbad4894a3f18734ad8ba7b9
7
- data.tar.gz: 91574f8a943ccdf59a555997ad0d50b656e861c78846eb9db4f55f0923b088164a3a846ea881f64115e04d2600dd86cee493be04b7269034972f70e5525c0c9b
6
+ metadata.gz: 8f60ad7c782fe168ccee264ae3d8589ad54fb07647a9adb85746ac35bea8ab55ac6f822480fc4900d536128a12ed966e977231f287921dc26e1085d921130a33
7
+ data.tar.gz: 1b83d507f815ed688db12e664202a335a019eb3cc5f4da33140190426a15f283a58283188c6101e55fbda3205b0e93d4c0ebbd1102885efe713430fbf5eebe92
data/kloudlite.rb CHANGED
@@ -14,7 +14,7 @@
14
14
  # "no Kloudlite login: pass token=, set KLOUDLITE_TOKEN, or run kloudlite login".
15
15
  #
16
16
  # Every public method takes KEYWORD arguments, so no caller has to remember an order; a
17
- # resource is always the keyword named after it (workspace:, environment:, session:,
17
+ # resource is always the keyword named after it (workspace:, environment:, desk:,
18
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"
@@ -25,7 +25,7 @@ require "timeout"
25
25
  require "uri"
26
26
 
27
27
  module Kloudlite
28
- VERSION = "0.2.2"
28
+ VERSION = "0.5.0"
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
 
@@ -56,11 +56,11 @@ module Kloudlite
56
56
  # A client-side wait ran out. A ::Timeout::Error, so a generic rescue still catches it.
57
57
  class TimeoutError < ::Timeout::Error; end
58
58
 
59
- # The naming rules every module shares. Mixed in privately; never part of the public surface.
59
+ # The naming rules (and the push body) every module shares. Mixed in privately; never part of the public surface.
60
60
  module Names
61
61
  private
62
62
 
63
- # "name" → [nil, name]; "team/name" → [team, name]. Workspaces, environments and sessions
63
+ # "name" → [nil, name]; "team/name" → [team, name]. Workspaces, environments and desks
64
64
  # send the pair as path segment +name+ plus ?owner=team, which the server folds back.
65
65
  def owned(s)
66
66
  s = s.to_s
@@ -75,10 +75,16 @@ module Kloudlite
75
75
  def seg(s)
76
76
  URI.encode_www_form_component(s.to_s).gsub("+", "%20")
77
77
  end
78
+
79
+ # The body of a workspace or environment push, shared so the two never drift apart.
80
+ def snapshot_body(message, volume, description, labels, branch, ttl_secs, never)
81
+ { message: message, volume: volume, description: description, labels: labels,
82
+ branch: branch, ttl_secs: ttl_secs, never: never }.compact
83
+ end
78
84
  end
79
85
 
80
86
  class Client
81
- attr_reader :workspaces, :environments, :sessions, :volumes,
87
+ attr_reader :workspaces, :environments, :desks, :volumes,
82
88
  :secrets, :connectors, :capsules, :pipelines
83
89
 
84
90
  def initialize(base_url: nil, token: nil, timeout: 30)
@@ -97,7 +103,7 @@ module Kloudlite
97
103
  @timeout = timeout
98
104
  @workspaces = Workspaces.new(self)
99
105
  @environments = Environments.new(self)
100
- @sessions = Sessions.new(self)
106
+ @desks = Desks.new(self)
101
107
  @volumes = Volumes.new(self)
102
108
  @secrets = Secrets.new(self)
103
109
  @connectors = Connectors.new(self)
@@ -217,9 +223,15 @@ module Kloudlite
217
223
  # Push a SNAPSHOT of the working copy — the one durable, restorable state (202). +volume+
218
224
  # names the volume and is required on its first push; +ttl_secs+ (3600..=31536000) or
219
225
  # never: true set its expiry. +push+ is the old name.
220
- def take_snapshot(workspace:, message: nil, volume: nil, ttl_secs: nil, never: nil)
226
+ # The push is a storage commit of the volume. +description+ and +labels+ describe the volume
227
+ # (a given one replaces the stored one). +branch+ creates that branch at the new commit or
228
+ # moves it there, and the workspace then has it checked out; without it the checked-out branch
229
+ # fast-forwards, and the answer carries +branch+ and, when the branch had moved meanwhile,
230
+ # +detached+.
231
+ def take_snapshot(workspace:, message: nil, volume: nil, description: nil, labels: nil,
232
+ branch: nil, ttl_secs: nil, never: nil)
221
233
  at("POST", workspace, "/snapshots",
222
- body: { message: message, volume: volume, ttl_secs: ttl_secs, never: never }.compact)
234
+ body: snapshot_body(message, volume, description, labels, branch, ttl_secs, never))
223
235
  end
224
236
  alias_method :push, :take_snapshot
225
237
 
@@ -229,8 +241,9 @@ module Kloudlite
229
241
  at("POST", workspace, "/clone", body: { name: to, task: task })
230
242
  end
231
243
 
232
- # A new workspace +to+ grafted onto a PUSHED +snapshot+ (a volume name, "name@N" or a snapshot
233
- # id) — also one whose workspace is long gone. +team+ (or to: "team/name") is required for a
244
+ # A new workspace +to+ grafted onto a PUSHED +snapshot+ (a volume name — its "base" branch,
245
+ # else its newest storage commit — "name@N", "name@<branch>" or a snapshot id) — also one
246
+ # whose workspace is long gone. +team+ (or to: "team/name") is required for a
234
247
  # team's volume. Absent overrides mean "whatever the snapshot froze".
235
248
  def restore(snapshot:, to:, team: nil, image: nil, packages: nil, quota_gb: nil)
236
249
  owner, name = owned(to)
@@ -461,11 +474,13 @@ module Kloudlite
461
474
  at("DELETE", environment)
462
475
  end
463
476
 
464
- # Push a SNAPSHOT of every service's data and the service list (202). +volume+ names the
465
- # volume and is required on its first push. +push+ is the old name.
466
- def take_snapshot(environment:, message: nil, volume: nil, ttl_secs: nil, never: nil)
477
+ # Push a SNAPSHOT of every service's data and the service list, a storage commit (202).
478
+ # +volume+ names the volume and is required on its first push; +description+, +labels+ and
479
+ # +branch+ are as in Workspaces#take_snapshot. +push+ is the old name.
480
+ def take_snapshot(environment:, message: nil, volume: nil, description: nil, labels: nil,
481
+ branch: nil, ttl_secs: nil, never: nil)
467
482
  at("POST", environment, "/snapshots",
468
- body: { message: message, volume: volume, ttl_secs: ttl_secs, never: never }.compact)
483
+ body: snapshot_body(message, volume, description, labels, branch, ttl_secs, never))
469
484
  end
470
485
  alias_method :push, :take_snapshot
471
486
 
@@ -500,96 +515,96 @@ module Kloudlite
500
515
  end
501
516
  end
502
517
 
503
- # Working sessions, over /v1/sessions: some of YOUR workspaces in one team, connected to one
504
- # environment. Many people's sessions connect to the same environment and collaborate through
505
- # it; an intercept a session takes is environment-wide, and the session owns it — only it can
506
- # release it, and removing the workspace or deleting the session releases it.
518
+ # Working desks, over /v1/desks: some of YOUR workspaces in one team, connected to one
519
+ # environment. Many people's desks connect to the same environment and collaborate through
520
+ # it; an intercept a desk takes is environment-wide, and the desk owns it — only it can
521
+ # release it, and removing the workspace or deleting the desk releases it.
507
522
  #
508
- # A session is named like an environment — "name" (personal) or "team/name" — or by its id
509
- # ("ses-…"); a workspace by its id, name or "team/name", sent verbatim.
510
- class Sessions
523
+ # A desk is named like an environment — "name" (personal) or "team/name" — or by its id
524
+ # ("desk-…"); a workspace by its id, name or "team/name", sent verbatim.
525
+ class Desks
511
526
  include Names
512
527
 
513
528
  def initialize(client)
514
529
  @c = client
515
530
  end
516
531
 
517
- # +environment+, when given, must be the session's team's: an id, a name or "team/name";
518
- # without one the session connects to nothing until +connect+. +ttl_secs+ (600..=2592000)
519
- # deletes the session after that long unused.
520
- def create(session:, environment: nil, ttl_secs: nil)
521
- team, name = owned(session)
522
- @c.request("POST", "/v1/sessions", body: { name: name, team: team, environment: environment, ttl_secs: ttl_secs })
532
+ # +environment+, when given, must be the desk's team's: an id, a name or "team/name";
533
+ # without one the desk connects to nothing until +connect+. +ttl_secs+ (600..=2592000)
534
+ # deletes the desk after that long unused.
535
+ def create(desk:, environment: nil, ttl_secs: nil)
536
+ team, name = owned(desk)
537
+ @c.request("POST", "/v1/desks", body: { name: name, team: team, environment: environment, ttl_secs: ttl_secs })
523
538
  end
524
539
 
525
- # Seconds unused before the session is deleted (600..=2592000); nil clears it.
526
- def set_ttl(session:, ttl_secs:)
527
- at("PUT", session, "/ttl", body: { ttl_secs: ttl_secs })
540
+ # Seconds unused before the desk is deleted (600..=2592000); nil clears it.
541
+ def set_ttl(desk:, ttl_secs:)
542
+ at("PUT", desk, "/ttl", body: { ttl_secs: ttl_secs })
528
543
  end
529
544
 
530
545
  def list(team: nil)
531
- @c.request("GET", "/v1/sessions", query: { team: team })
546
+ @c.request("GET", "/v1/desks", query: { team: team })
532
547
  end
533
548
 
534
- # The session with its +workspaces+ and the +intercepts+ it holds.
535
- def get(session:)
536
- at("GET", session)
549
+ # The desk with its +workspaces+ and the +intercepts+ it holds.
550
+ def get(desk:)
551
+ at("GET", desk)
537
552
  end
538
553
 
539
554
  # Releases its intercepts and lets its workspaces go — never deletes a workspace.
540
- def delete(session:)
541
- at("DELETE", session)
555
+ def delete(desk:)
556
+ at("DELETE", desk)
542
557
  end
543
558
 
544
- # Sets, switches or (nil) clears the session's environment. Its intercepts in the old
545
- # environment are released first; deleting an environment disconnects its sessions the same way.
546
- def connect(session:, environment:)
547
- at("PUT", session, "/environment", body: { environment: environment })
559
+ # Sets, switches or (nil) clears the desk's environment. Its intercepts in the old
560
+ # environment are released first; deleting an environment disconnects its desks the same way.
561
+ def connect(desk:, environment:)
562
+ at("PUT", desk, "/environment", body: { environment: environment })
548
563
  end
549
564
 
550
- # Stop the session and every workspace in it (202, {"stopped" => [ids]}); capsules and the
565
+ # Stop the desk and every workspace in it (202, {"stopped" => [ids]}); capsules and the
551
566
  # environment are untouched.
552
- def stop(session:)
553
- at("POST", session, "/stop")
567
+ def stop(desk:)
568
+ at("POST", desk, "/stop")
554
569
  end
555
570
 
556
- # Create a workspace +workspace+ (a bare name) managed by the session, in its team (201). The
557
- # session controls it from then on; it takes the inputs of Workspaces#create.
558
- def create_workspace(session:, workspace:, quota_gb:, image: nil, packages: nil, ttl_secs: nil, env: nil)
559
- at("POST", session, "/workspaces",
571
+ # Create a workspace +workspace+ (a bare name) managed by the desk, in its team (201). The
572
+ # desk controls it from then on; it takes the inputs of Workspaces#create.
573
+ def create_workspace(desk:, workspace:, quota_gb:, image: nil, packages: nil, ttl_secs: nil, env: nil)
574
+ at("POST", desk, "/workspaces",
560
575
  body: { name: workspace, quota_gb: quota_gb, image: image, packages: packages,
561
576
  ttl_secs: ttl_secs, env: env }.compact)
562
577
  end
563
578
 
564
- # Delete a workspace the session manages, releasing its intercepts first (204); snapshots stay.
565
- def delete_workspace(session:, workspace:)
566
- at("DELETE", session, "/workspaces/#{seg(workspace)}")
579
+ # Delete a workspace the desk manages, releasing its intercepts first (204); snapshots stay.
580
+ def delete_workspace(desk:, workspace:)
581
+ at("DELETE", desk, "/workspaces/#{seg(workspace)}")
567
582
  end
568
583
 
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)))
584
+ # Create a capsule managed by the desk (202), in its team and reaching its environment.
585
+ # Same inputs as Capsules#create (+team+ must be the desk's).
586
+ def create_capsule(desk:, cmd:, **options)
587
+ Capsule.new(@c, at("POST", desk, "/capsules", body: Capsules.body(cmd: cmd, **options)))
573
588
  end
574
589
 
575
590
  # Send everything that calls +service+ in the environment to +workspace+ (a member), +ports+
576
591
  # mapping each service port to the workspace port that answers it ({ 8080 => 3000 }); an
577
592
  # unmapped port answers on the same number.
578
- def intercept(session:, service:, workspace:, ports: nil)
579
- at("POST", session, "/intercepts",
593
+ def intercept(desk:, service:, workspace:, ports: nil)
594
+ at("POST", desk, "/intercepts",
580
595
  body: { service: service, workspace: workspace,
581
596
  ports: (ports || {}).map { |s, w| { service: Integer(s), workspace: Integer(w) } } })
582
597
  end
583
598
 
584
- def release(session:, service:)
585
- at("DELETE", session, "/intercepts/#{seg(service)}")
599
+ def release(desk:, service:)
600
+ at("DELETE", desk, "/intercepts/#{seg(service)}")
586
601
  end
587
602
 
588
603
  private
589
604
 
590
- def at(method, session, tail = "", body: nil)
591
- owner, name = owned(session)
592
- @c.request(method, "/v1/sessions/#{seg(name)}#{tail}", body: body, query: { owner: owner })
605
+ def at(method, desk, tail = "", body: nil)
606
+ owner, name = owned(desk)
607
+ @c.request(method, "/v1/desks/#{seg(name)}#{tail}", body: body, query: { owner: owner })
593
608
  end
594
609
  end
595
610
 
@@ -657,9 +672,10 @@ module Kloudlite
657
672
  @c = client
658
673
  end
659
674
 
660
- # +kind+ is "workspace" or "environment"; +owner+ a handle or team slug.
661
- def list(kind: nil, owner: nil)
662
- @c.request("GET", "/v1/volumes", query: { kind: kind, owner: owner })
675
+ # +kind+ is "workspace" or "environment"; +owner+ a handle or team slug; +label+ keeps the
676
+ # volumes that carry it.
677
+ def list(kind: nil, owner: nil, label: nil)
678
+ @c.request("GET", "/v1/volumes", query: { kind: kind, owner: owner, label: label })
663
679
  end
664
680
 
665
681
  # The chain of PUSHED snapshots, newest first — each row a restore target.
@@ -682,12 +698,32 @@ module Kloudlite
682
698
  @c.request("DELETE", "/v1/volumes/#{seg(volume)}")
683
699
  end
684
700
 
685
- # One named volume; +owner+ is your handle or a team slug.
701
+ # One named volume; +owner+ is your handle or a team slug. It carries +description+,
702
+ # +labels+ and +branches+ (each branch with the storage commit number it points at).
686
703
  def get(owner:, name:)
687
704
  @c.request("GET", named(owner, name))
688
705
  end
689
706
 
690
- # The versions of a named volume, newest first.
707
+ # Set or clear the description and the labels; nil leaves a field as it is, "" removes the
708
+ # description and [] the labels. Answers the volume.
709
+ def describe(owner:, name:, description: nil, labels: nil)
710
+ @c.request("PATCH", named(owner, name),
711
+ body: { description: description, labels: labels }.compact)
712
+ end
713
+
714
+ # Create +branch+ on a storage commit, or move it there (like git branch -f): give +version+
715
+ # (the commit number) or +snapshot+ (a snapshot id), not both. Answers the volume.
716
+ def set_branch(owner:, name:, branch:, version: nil, snapshot: nil)
717
+ @c.request("PUT", named(owner, name, "/branches/#{seg(branch)}"),
718
+ body: { version: version, snapshot: snapshot }.compact)
719
+ end
720
+
721
+ # Remove a branch (204); its storage commit stays.
722
+ def delete_branch(owner:, name:, branch:)
723
+ @c.request("DELETE", named(owner, name, "/branches/#{seg(branch)}"))
724
+ end
725
+
726
+ # The storage commits of a named volume, newest first; each row carries the +branches+ on it.
691
727
  def versions(owner:, name:)
692
728
  @c.request("GET", named(owner, name, "/versions"))
693
729
  end
@@ -697,7 +733,8 @@ module Kloudlite
697
733
  @c.request("DELETE", named(owner, name))
698
734
  end
699
735
 
700
- # Delete version +n+ (204); deleting the last one deletes the volume.
736
+ # Delete storage commit +n+ (204); deleting the last one deletes the volume. A branch's
737
+ # commit is refused (409).
701
738
  def delete_version(owner:, name:, n:)
702
739
  @c.request("DELETE", named(owner, name, "/versions/#{Integer(n)}"))
703
740
  end
@@ -721,7 +758,7 @@ module Kloudlite
721
758
  include Names
722
759
 
723
760
  # The POST /v1/capsules body; refuses a missing +cmd+ before anything is sent. Shared with
724
- # Sessions#create_capsule — not public surface.
761
+ # Desks#create_capsule — not public surface.
725
762
  def self.body(cmd:, image: nil, packages: nil, from_workspace: nil, from_snapshot: nil, team: nil,
726
763
  tty: nil, stdin: nil, timeout_s: nil, network: nil, env: nil, cpu: nil,
727
764
  memory_gb: nil, disk_gb: nil)
@@ -742,8 +779,8 @@ module Kloudlite
742
779
  # is the program then its arguments. +tty+ runs it on a pty; +stdin+ keeps input open for
743
780
  # attach. +timeout_s+ is 10..=86400. +from_workspace+ is an id, "name" or "team/name";
744
781
  # +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 capsule is made with
746
- # Sessions#create_capsule. Unset keywords are omitted, so the server's defaults apply.
782
+ # "internet" or "none"; +cpu+ 1..=8, +memory_gb+ 1..=32. A desk's capsule is made with
783
+ # Desks#create_capsule. Unset keywords are omitted, so the server's defaults apply.
747
784
  def create(cmd:, **options)
748
785
  Capsule.new(@c, @c.request("POST", "/v1/capsules", body: Capsules.body(cmd: cmd, **options)))
749
786
  end
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.3.0
4
+ version: 0.5.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-07 00:00:00.000000000 Z
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description:
14
14
  email: