hotcell-client-legacy 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c542ad1f9adfdf8dad3a0c61984107ee91ec79fe55201d88bc08050a0c57ea1
-  data.tar.gz: 55e9c151471e12b47aafa3a49bf8790fc8610f4de1e04bd5c520c4d1fd5eab7d
+  metadata.gz: c69cef47499d5d65909fa3be45dbcc447b56d9f9fec0c5f2bd1fbb65b9b63e88
+  data.tar.gz: 4c251a71745d240adc39fb144fe0695baca23a2b65c4a0b005ea1e6209c44182
 SHA512:
-  metadata.gz: 7686e7b921b05c0913dac6a24eb95987be455526c4d9439442767faa0732c3db515b49935c664c27578bca799977066e11a32a203a92e6f707ae3956af8ac902
-  data.tar.gz: e1ae1d57ed45e3620dbd71d98b171f3a3034a3e70ddb190fae0365cf6a9a9f142cca8326bec1cb5f34e4bdcde03fc7ed916a0fe3a024805bf558e6be026b30a9
+  metadata.gz: b1efde0d7580dcf53b06db03a8256216de8b5c20085239d5eb2873cfb8668a20e289f21c6892d0cea56986d2c6448ea7552def34896f25c1418896115c71678f
+  data.tar.gz: b5aff56e7f0c394496865d9e9700fef4753e13cd69f3a29b8a3fc688e6b16cb43cad76308d73d1b818a53fd92d019c3a8ab6eac1c1b169b5d3789a72a7fd8ccd

data/README.md

@@ -1,3 +1,3 @@
 # hotcell-client-legacy
 
-Part of [HotCell](https://github.com/basecamp/hotcell). See [docs/client-legacy.md](https://github.com/basecamp/hotcell/blob/master/docs/client-legacy.md).
+Part of [Hot Cell](https://github.com/basecamp/hotcell). See [docs/client-legacy.md](https://github.com/basecamp/hotcell/blob/master/docs/client-legacy.md).

data/lib/hot_cell/client/legacy.rb

@@ -14,7 +14,7 @@ module HotCell
     #
     # Written for Ruby 1.9.3, so it uses no keyword arguments, `&.`, `String#b` or `IO#wait_readable`.
     class Legacy
-      VERSION = "1.1.0"
+      VERSION = "1.2.0"
 
       PROTOCOL_VERSION = 1
       MAX_RESPONSE_BYTES = 65_536
@@ -29,7 +29,7 @@ module HotCell
       INPUT_MODE = 0o640
       OUTPUT_MODE = 0o620
 
-      # A cell's verdict on a request that did not succeed, with the readers of hotcell-core's HotCell::Failure.
+      # A cell's answer to a request that did not succeed, with the readers of hotcell-core's HotCell::Failure.
       class Failure
         attr_reader :code, :cause, :signal, :error_class, :message, :stderr
 
@@ -56,27 +56,50 @@ module HotCell
         def to_s
           [ (code unless code.empty?), cause, error_class, message ].compact.join(": ")
         end
+
+        # Included in both failure classes, so `rescue Failure::Exception` catches either and
+        # `hot_cell_failure` reads the failure, as with hotcell-client's HotCell::Failure::Exception. The
+        # classes share no superclass, so rescuing one by name never catches the other: a permanent failure
+        # may be written down against a file forever, and a transient one must be retried.
+        module Exception
+          attr_reader :hot_cell_response
+
+          def initialize(response)
+            @hot_cell_response = response
+            super(response.failure.to_s)
+          end
+
+          def hot_cell_failure
+            hot_cell_response.failure
+          end
+        end
       end
 
-      # Included in both failure classes, so `rescue Verdict` catches either and `hot_cell_failure` reads the
-      # failure, as with hotcell-client's HotCell::Verdict. The classes share no superclass, so rescuing one by
-      # name never catches the other: a permanent failure may be written down against a file forever, and a
-      # transient one must be retried.
-      module Verdict
-        attr_reader :hot_cell_failure
+      # The outcome of one call, success or failure. `timing` is the cell's own open map, such as
+      # `queued_ms` and `perform_ms`, and is empty when the answer carried none. `duration_ms` is the time this
+      # client measures across the connect, the send and the read, so `duration_ms` minus `perform_ms` is
+      # transport plus queueing.
+      class Response
+        attr_reader :result, :failure, :timing, :duration_ms
+
+        def initialize(result, failure, timing, duration_ms)
+          @result = result
+          @failure = failure
+          @timing = timing
+          @duration_ms = duration_ms
+        end
 
-        def initialize(failure)
-          @hot_cell_failure = failure
-          super(failure.to_s)
+        def ok?
+          failure.nil?
         end
       end
 
       class PermanentFailure < StandardError
-        include Verdict
+        include Failure::Exception
       end
 
       class TransientFailure < StandardError
-        include Verdict
+        include Failure::Exception
       end
 
       class Timeout < StandardError; end
@@ -93,7 +116,7 @@ module HotCell
         @group = options[:group]
       end
 
-      # Returns the operation's result, a Hash with String keys. Raises PermanentFailure or TransientFailure
+      # Returns a Response whose result is a Hash with String keys. Raises PermanentFailure or TransientFailure
       # according to the `permanent` flag on the cell's answer; a failure with no answer at all is transient.
       def perform(operation, inputs, outputs, payload = {})
         inputs = [ inputs ] unless inputs.is_a?(Array)
@@ -104,19 +127,41 @@ module HotCell
         share inputs, INPUT_MODE
         share outputs, OUTPUT_MODE
 
-        line = JSON.generate("v" => PROTOCOL_VERSION, "op" => operation.to_s, "inputs" => inputs.size,
-                             "outputs" => outputs.size, "payload" => payload) + "\n"
+        call socket_path, operation.to_s, inputs, outputs, payload
+      end
 
-        answer = exchange(line, inputs + outputs)
-        return answer["result"] if answer["ok"]
+      # The cell's static description, from the control socket beside the work socket. Raises as `perform` does.
+      def describe
+        call control_socket_path, "hotcell.describe", [], [], {}
+      end
 
-        # Built rather than passed to raise, because Ruby 2.x reads a trailing Hash given to raise as its options
-        # and takes `cause` out of it.
-        failure = Failure.new(sanitize(answer["error"]))
-        raise (failure.permanent? ? PermanentFailure : TransientFailure).new(failure)
+      # The cell's counters, from the control socket beside the work socket. Raises as `perform` does.
+      def metrics
+        call control_socket_path, "hotcell.metrics", [], [], {}
       end
 
       private
+        def control_socket_path
+          File.join File.dirname(socket_path), "control.sock"
+        end
+
+        def call(path, operation, inputs, outputs, payload)
+          line = JSON.generate("v" => PROTOCOL_VERSION, "op" => operation, "inputs" => inputs.size,
+                               "outputs" => outputs.size, "payload" => payload) + "\n"
+
+          started = now
+          answer = exchange(path, line, inputs + outputs)
+          duration_ms = (now - started) * 1000
+          timing = answer["timing"].is_a?(Hash) ? answer["timing"] : {}
+          return Response.new(answer["result"], nil, timing, duration_ms) if answer["ok"]
+
+          # Built rather than passed to raise, because Ruby 2.x reads a trailing Hash given to raise as its options
+          # and takes `cause` out of it.
+          failure = Failure.new(sanitize(answer["error"]))
+          response = Response.new(nil, failure, timing, duration_ms)
+          raise (failure.permanent? ? PermanentFailure : TransientFailure).new(response)
+        end
+
         def share(ios, mode)
           return if group.nil?
 
@@ -126,10 +171,10 @@ module HotCell
           end
         end
 
-        def exchange(line, descriptors)
+        def exchange(path, line, descriptors)
           deadline = now + timeout
           socket = Socket.new(:UNIX, :STREAM)
-          connect socket, deadline
+          connect socket, path, deadline
           deliver socket, line, descriptors, deadline
           response = receive(socket, deadline)
           return unavailable("the connection closed with no response, so the cell's supervisor is gone") if response.nil?
@@ -147,8 +192,8 @@ module HotCell
         # with no deadline, and a supervisor that has stopped calling `accept` leaves it full. Linux answers a
         # non-blocking connect to that backlog with EAGAIN and leaves the socket unconnected, so it is retried
         # rather than waited on: an unconnected Unix socket is always writable, and `select` would not wait.
-        def connect(socket, deadline)
-          socket.connect_nonblock Socket.sockaddr_un(socket_path)
+        def connect(socket, path, deadline)
+          socket.connect_nonblock Socket.sockaddr_un(path)
         rescue Errno::EAGAIN
           remaining = deadline - now
           raise Timeout unless remaining > 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotcell-client-legacy
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -9,7 +9,7 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Call an operation in a HotCell container from an application that cannot
+description: Call an operation in a Hot Cell container from an application that cannot
   run hotcell-client. One file, the standard library only, and legacy Ruby versions.
 email:
 - mike@37signals.com
@@ -26,8 +26,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/basecamp/hotcell
-  source_code_uri: https://github.com/basecamp/hotcell/tree/v1.1.0/hotcell-client-legacy
-  changelog_uri: https://github.com/basecamp/hotcell/blob/v1.1.0/CHANGELOG.md
+  source_code_uri: https://github.com/basecamp/hotcell/tree/v1.2.0/hotcell-client-legacy
+  changelog_uri: https://github.com/basecamp/hotcell/blob/v1.2.0/CHANGELOG.md
   documentation_uri: https://basecamp.github.io/hotcell/
   bug_tracker_uri: https://github.com/basecamp/hotcell/issues
   rubygems_mfa_required: 'true'
@@ -45,7 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.6
 specification_version: 4
-summary: Call a HotCell from a legacy Ruby version, with no dependencies.
+summary: Call a Hot Cell from a legacy Ruby version, with no dependencies.
 test_files: []