kosa8 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '059d3ca9753fb52d517a80038164038e51621d2ae4a2393fcb8f79481e9c8c95'
-  data.tar.gz: 10c6b5dd4914af9371fe21b17230df7ac38c85275fbb16c1fa60e1f10487bbc3
+  metadata.gz: fbd21499fe850f6b1c9055f9451c06500e9b779e60d880426afa850fc8a69ce5
+  data.tar.gz: 786b60910b4a591d9fec38b5b0b5d2623fd805934ff8508337ceec1f7e3159b4
 SHA512:
-  metadata.gz: 8774ce6bba2044d40ec5f051d84be6b057944469bda072eb52bacb8104d025f8a6cda96f5da6ca244c0eeee1207730b42f096118a93a96ad3d9454a8a740a2b0
-  data.tar.gz: 2207cecb3af2ca7dadfe4aa1252f29a0886b5e583534da78fe04682e5882b04235a9ff6a52fa16b546a9a1f3ad300c006a2b5413b92fe4350ca324448ebe7fed
+  metadata.gz: f5e5ea9ecbde4e0fdd2085b89d00ac7145485a4f6f2866bbde4986672a9e24215e3af27b9fa89aed98adc010698359d84ad435343d737f120c7faa37c7657af8
+  data.tar.gz: 946d830b7d1ecfba2962857cded5f61c8bcb9d621fc8d0af7f3985f755272811934175bdff469aabe1a442c740a457a8ea6cecc32eba2b5c0d993344a818c799

data/README.md

@@ -41,6 +41,8 @@ Daemon: `health`, `version`, `pull`.
 Sandboxes: `list_sandboxes`, `get_sandbox`, `create_sandbox`, `start_sandbox`, `stop_sandbox`, `delete_sandbox`,
 `pull_into_sandbox`, `sandbox_images`, `sandbox_containers`, `sandbox_egress`.
 Processes: `run`, `start_container`, `exec`, `exec_frames`, `start_interactive`, `write_stdin`, `attach`.
+
+Streaming calls (`run`, `exec`, `exec_frames`, `attach`) wait as long as the command runs unless you pass `timeout:`; a timeout stops the client waiting, not the command. `write_stdin` sends the container's whole stdin in one call (the daemon closes stdin at the end of the body), so pass an IO or an Enumerable to stream input; a second call raises.
 Snapshots: `snapshot`, `list_snapshots`, `restore_snapshot`, `delete_snapshot`, `fork`, `explore`.
 Checkpoints: `checkpoint`, `list_checkpoints`, `rewind` (store: `~/.kosa8/checkpoints.json`, flock-shared with the CLI).
 `client.sandbox(id)` binds them to one sandbox.

data/lib/kosa8/checkpoints.rb

@@ -42,10 +42,12 @@ module Kosa8
   # atomically), locked with the same flock on checkpoints.json.lock, so
   # `kosa8 rewind` sees checkpoints taken here and the other way round.
   class FileCheckpointStore
-    attr_reader :path
+    attr_reader :path, :lock_timeout
 
-    def initialize(path = nil)
+    # lock_timeout: seconds to wait for checkpoints.json.lock (10, as @kosa8/sdk).
+    def initialize(path = nil, lock_timeout: 10)
       @path = path || File.join(Dir.home, ".kosa8", "checkpoints.json")
+      @lock_timeout = lock_timeout
       @mu = Mutex.new
     end
 
@@ -60,7 +62,7 @@ module Kosa8
       @mu.synchronize do
         FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
         File.open("#{@path}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
-          lock.flock(File::LOCK_EX)
+          acquire(lock)
           d = load
           r = yield d
           tmp = "#{@path}.tmp"
@@ -71,6 +73,19 @@ module Kosa8
         end
       end
     end
+
+    private
+
+    def acquire(lock)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @lock_timeout
+      until lock.flock(File::LOCK_EX | File::LOCK_NB)
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          raise CheckpointError, "timed out after #{@lock_timeout}s waiting for #{@path}.lock; another kosa8 " \
+                                 "process is holding it"
+        end
+        sleep 0.05
+      end
+    end
   end
 
   # The stack logic of pkg/checkpoint over any store. Records are hashes with

data/lib/kosa8/client.rb

@@ -28,6 +28,8 @@ module Kosa8
       @transport = Transport.new(socket_path: socket_path, host: host, token: token, insecure: insecure, actor: actor,
                                  agent_token: agent_token, headers: headers, timeout: timeout, env: env)
       @checkpoints = CheckpointBook.new(checkpoint_store || FileCheckpointStore.new)
+      @stdin_sent = {}
+      @stdin_mu = Mutex.new
     end
 
     # --- daemon ---------------------------------------------------------------
@@ -163,7 +165,22 @@ module Kosa8
     end
 
     # POST …/containers/{cid}/stdin: a String, an IO, or an Enumerable of chunks (sent chunked).
+    #
+    # The request body is the container's whole stdin: the daemon closes stdin
+    # when the body ends, so this can be called once per container. To feed
+    # input over time, pass an IO or an Enumerable that yields as it goes.
+    # A second call raises instead of reporting success for input the process
+    # would never see.
     def write_stdin(sandbox, container, data, approval: nil)
+      key = [sandbox.to_s, container.to_s]
+      @stdin_mu.synchronize do
+        if @stdin_sent[key]
+          raise Error, "stdin of container #{container} in #{sandbox} was already sent and is closed: the daemon " \
+                       "treats one write_stdin body as the whole of stdin. Pass an IO or an Enumerable to stream input"
+        end
+
+        @stdin_sent[key] = true
+      end
       @transport.json("POST", sb(sandbox, "containers", Kosa8.enc(container), "stdin"), raw_body: data, approval: approval)
     end
 
@@ -265,8 +282,22 @@ module Kosa8
     # Save a restore point: a snapshot <sandbox>-ckpt-<n> on the sandbox's stack,
     # the same store `kosa8 checkpoint` uses; the oldest is evicted past 10.
     def checkpoint(sandbox, label: "", approval: nil)
+      snap = nil
+      # Two checkpoints taken at once (here or by the CLI) can pick the same
+      # next id; the loser's snapshot is refused with 409. The winner records
+      # its id only once its snapshot is done, so step past the taken id
+      # rather than re-reading the store.
       cid, evict = @checkpoints.next_id(sandbox)
-      snap = snapshot(sandbox, id: cid, approval: approval)
+      10.times do |attempt|
+        begin
+          snap = snapshot(sandbox, id: cid, approval: approval)
+          break
+        rescue ConflictError => e
+          raise if attempt == 9 || !(e.daemon_message || e.message).to_s.include?("already exists")
+
+          cid = "#{sandbox}-ckpt-#{CheckpointBook.seq(cid, sandbox) + 1}"
+        end
+      end
       evict.each do |old| # evict only once the replacement exists
         delete_snapshot(old, approval: approval)
       rescue Error
@@ -292,7 +323,8 @@ module Kosa8
       begin
         restored = restore_snapshot(target["id"], name: sandbox, approval: approval)
       rescue Error => e
-        raise CheckpointError, "restore failed and #{sandbox} is now stopped: #{e.message} — recover with " \
+        raise CheckpointError, "restore failed and #{sandbox} no longer exists (it was deleted to free its name " \
+                               "for the restore): #{e.message} — the checkpoint is intact; recover with " \
                                "restore_snapshot(#{target['id'].inspect}, name: #{sandbox.inspect})"
       end
       dropped = []
@@ -397,7 +429,7 @@ module Kosa8
         rescue Error => e
           b.error = e.message
           b.output = (e.stdout + e.stderr).chomp if e.is_a?(StreamError)
-          break if e.is_a?(TimeoutError) || b.error !~ TRANSIENT
+          break if e.is_a?(TimeoutError) || b.error !~ TRANSIENT || attempt == 3
 
           sleep((attempt + 1) * 0.5)
         end
@@ -464,6 +496,22 @@ module Kosa8
       @client.explore(@id, variants, **kw)
     end
 
+    def exec_frames(container, args, **kw, &blk)
+      @client.exec_frames(@id, container, args, **kw, &blk)
+    end
+
+    def start_interactive(image, args = [], **kw)
+      @client.start_interactive(@id, image, args, **kw)
+    end
+
+    def write_stdin(container, data, **kw)
+      @client.write_stdin(@id, container, data, **kw)
+    end
+
+    def attach(container, **kw)
+      @client.attach(@id, container, **kw)
+    end
+
     { start: :start_sandbox, stop: :stop_sandbox, delete: :delete_sandbox, snapshot: :snapshot,
       checkpoint: :checkpoint, rewind: :rewind }.each do |name, target|
       define_method(name) { |**kw| @client.public_send(target, @id, **kw) }

data/lib/kosa8/errors.rb

@@ -4,14 +4,14 @@ module Kosa8
   # Every error this gem raises. The daemon's own words are kept in
   # +daemon_message+ and +remediation+, as @kosa8/sdk does.
   class Error < StandardError
-    attr_reader :status, :daemon_message, :remediation, :method, :path, :body
+    attr_reader :status, :daemon_message, :remediation, :http_method, :path, :body
 
     def initialize(message = nil, status: nil, daemon_message: nil, remediation: nil, method: nil, path: nil, body: nil)
       super(message)
       @status = status
       @daemon_message = daemon_message
       @remediation = remediation
-      @method = method
+      @http_method = method
       @path = path
       @body = body
     end
@@ -50,6 +50,9 @@ module Kosa8
   class CheckpointError < Error; end
   class TimeoutError < Error; end
 
+  # Raised when a frame stream carries something that is not NDJSON.
+  class ProtocolError < Error; end
+
   BY_STATUS = {
     400 => BadRequestError, 401 => AuthError, 403 => PolicyError,
     404 => NotFoundError, 409 => ConflictError, 501 => UnsupportedError

data/lib/kosa8/transport.rb

@@ -105,6 +105,17 @@ module Kosa8
     end
   end
 
+  # Carries an exception raised by a caller's callback past raw's network
+  # rescue; raw re-raises the original.
+  class CallbackFailure < Exception # rubocop:disable Lint/InheritException
+    attr_reader :cause_error
+
+    def initialize(err)
+      super(err.message)
+      @cause_error = err
+    end
+  end
+
   # Sends requests to the daemon; the client builds on it.
   class Transport
     attr_reader :endpoint
@@ -121,7 +132,7 @@ module Kosa8
     end
 
     # One request; yields the Net::HTTPResponse (body unread) and returns the block's value.
-    def raw(method, path, query: nil, body: nil, raw_body: nil, approval: nil, timeout: nil)
+    def raw(method, path, query: nil, body: nil, raw_body: nil, approval: nil, timeout: nil, stream: false)
       full = (@endpoint.kind == :tcp ? @endpoint.base_path.to_s : "") + path
       q = (query || {}).each_with_object([]) do |(k, v), a|
         next if v.nil? || v == false
@@ -153,9 +164,15 @@ module Kosa8
       if t
         http.open_timeout = [t, 30].min
         http.read_timeout = t
+      elsif stream
+        # A run, exec or attach can be silent for as long as the command
+        # likes; Net::HTTP's 60 s default would cut it off. Wait for it.
+        http.read_timeout = nil
       end
       begin
         http.start { |h| h.request(req) { |resp| return yield(resp) } }
+      rescue CallbackFailure => e
+        raise e.cause_error
       rescue Net::ReadTimeout, Net::OpenTimeout => e
         raise TimeoutError.new("#{method} #{path} timed out talking to #{@endpoint.target}: #{e.message}",
                                method: method, path: path)
@@ -179,21 +196,38 @@ module Kosa8
 
     # A request whose answer is NDJSON frames; yields each, data decoded from base64.
     def frames(method, path, **kw)
-      raw(method, path, **kw) do |resp|
+      raw(method, path, stream: true, **kw) do |resp|
         if resp.code.to_i >= 400
           raise Kosa8.error_from_response(resp.code.to_i, decode(resp.read_body.to_s), method: method, path: path)
         end
 
         buf = +""
+        emit = lambda do |line|
+          next if line.empty?
+
+          frame = begin
+            Kosa8.decode_frame(JSON.parse(line))
+          rescue JSON::ParserError, ArgumentError => e
+            raise ProtocolError.new("#{method} #{path}: the daemon sent a frame that is not valid NDJSON " \
+                                    "(#{e.message}): #{line[0, 200].inspect}", method: method, path: path)
+          end
+          # Errors from the caller's own callbacks must come out as they are,
+          # not relabelled as a lost connection by the rescue in raw.
+          begin
+            yield frame
+          rescue Kosa8::Error
+            raise
+          rescue StandardError => e
+            raise CallbackFailure.new(e)
+          end
+        end
         resp.read_body do |chunk|
           buf << chunk
           while (i = buf.index("\n"))
-            line = buf.slice!(0..i).strip
-            yield Kosa8.decode_frame(JSON.parse(line)) unless line.empty?
+            emit.call(buf.slice!(0..i).strip)
           end
         end
-        line = buf.strip
-        yield Kosa8.decode_frame(JSON.parse(line)) unless line.empty?
+        emit.call(buf.strip)
         nil
       end
     end

data/lib/kosa8/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kosa8
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kosa8
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - kosa8