hotcell-client 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ba1bb0047670fef637ea304c58ca6589c68c68491b84df357745f4c35dba740
-  data.tar.gz: ec3e1cac68b95f6af2c00982538ce95a19a1257014c1c8bec53a49a860e68f83
+  metadata.gz: 68844b319a6ccd7835ede7e0c6b364fa3bc3d7a29a211b921c8f6adc2198902a
+  data.tar.gz: d8e6dcbd8421be86289184abfca146020d1ae40434beceaffce48464b20d5e45
 SHA512:
-  metadata.gz: 26eaf78d5f835becb66508a423f91f73223e843d531e6d44723c5d635f9cab1b16f7560f58fc322ab25b50c6503d6d6227d88665a0ca2f81533de19e16f3b84d
-  data.tar.gz: e12b678e13d8327c502ae440e923970dd7bcd32b1e828ba9d1ffedabbf724e678c6d36a63bf412d50b289be46c513698f62af187d4a35a6ee13a8d573bfe16a5
+  metadata.gz: 1f93722bb025dde95a5399d987b94e41d38512ca47f51966a1f1032b104c5a3fda5d90727500c3c49202faa8e6b865105d7e269e2777b0ad8a4f310437fab477
+  data.tar.gz: d7a833dec4d14ae77456f998ba9915b06cb6f5502d2e11342e4a5e8d2ef0e498d675a723793ed223199b70810ffbd70ebf6aa82140800cd4b88e99613e38caa0

data/README.md

@@ -1,3 +1,3 @@
 # hotcell-client
 
-Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README.
+Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README.

data/lib/hot_cell/cell.rb

@@ -11,8 +11,8 @@ module HotCell
   class Cell
     attr_reader :name, :timeout, :control_timeout, :permanent, :transient, :transport
 
-    # `timeout` covers work, so it is sized to clear the cell's `answer_within` and a saturated cell reports
-    # its own verdict rather than a transport failure. `control_timeout` covers `describe` and `metrics`,
+    # `timeout` covers work, so it is sized to clear the cell's `answer_within` and a saturated cell answers
+    # for itself rather than arriving as a transport failure. `control_timeout` covers `describe` and `metrics`,
     # which the supervisor answers inline with no fork or queue — so it is short on purpose. Sharing one
     # number would give the call whose job is to say "this cell is down" the patience of a video transcode.
     #
@@ -189,7 +189,7 @@ module HotCell
       # Being bound tighter than that is defensible and it is a choice, not a mistake. A synchronous
       # representation request wants it tighter, because a thread held for sixty seconds is a thread not
       # serving traffic. A background job wants it looser, so it receives `capacity` or `killed` and can act
-      # on them rather than guessing from a socket error. Both outcomes are transient, so neither is
+      # on them rather than guessing from a socket error. Both failures are transient, so neither is
       # misclassified — which is the only reason this is safe.
       # The cell states this; adding it up here would mean guessing at stages only the supervisor knows about.
       # A cell too old to report it says nothing, which is the right answer for a number we cannot know.
@@ -199,7 +199,7 @@ module HotCell
 
         HotCell.logger.warn "hotcell #{name}: this client waits #{seconds timeout} and the cell says it may " \
                             "take #{seconds needed} to answer, so a saturated cell will arrive here as a " \
-                            "transport failure rather than as its own verdict. Deliberate on a synchronous " \
+                            "transport failure rather than as the cell's own answer. Deliberate on a synchronous " \
                             "path; a mistake for a background job."
       end
 

data/lib/hot_cell/client/version.rb

@@ -3,6 +3,6 @@
 module HotCell
   # A class and not a module: this file loads before hot_cell/client.rb opens the same name.
   class Client
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
   end
 end

data/lib/hot_cell/client.rb

@@ -106,6 +106,11 @@ module HotCell
       ActiveSupport::Notifications.instrument "perform.hot_cell", operation: self.class.operation, cell: cell.name do |event|
         response = verify_output(cell.transport.call(cell, line, descriptors), outputs)
         publish event, cell, response, inputs, outputs
+      # The transport answers its own failures with a code, so what lands here is the caller's own exception,
+      # such as its request timeout, and the call has no answer to describe.
+      rescue Exception
+        event[:code] = "interrupted"
+        raise
       end
 
       raise_for response, cell
@@ -160,9 +165,10 @@ module HotCell
       # `code` belongs on the event rather than only on an exception. A caller configured to treat
       # `unreadable` as data would otherwise make those requests invisible, and unreadable rates are exactly
       # what you want to watch after a library upgrade. `capacity` matters for the same reason: without its
-      # rate you cannot size a worker pool.
+      # rate you cannot size a worker pool. It is `ok` on success, so no subscriber reads success from a
+      # missing code.
       #
-      # The cause, signal and verdict go with it, because the code alone cannot classify a kill: `killed`
+      # The cause, signal and `permanent` go with it, because the code alone cannot classify a kill: `killed`
       # is permanent for fsize and memory and transient for deadline and crashed. A subscriber with only
       # the code filed every fsize kill as transient. `permanent` is the Failure's own answer, so no
       # subscriber re-derives it.
@@ -178,7 +184,7 @@ module HotCell
       def publish(event, cell, response, inputs, outputs)
         failure = response.failure
 
-        event[:code] = failure&.code
+        event[:code] = failure ? failure.code : "ok"
         event[:cause] = failure&.cause
         event[:signal] = failure&.signal
         event[:stderr] = failure&.stderr
@@ -200,7 +206,7 @@ module HotCell
         return if response.ok?
 
         failure = response.failure
-        error = Verdict.wrap(cell.exception_for(failure).new(failure.to_s), failure)
+        error = Failure::Exception.wrap(cell.exception_for(failure).new(failure.to_s), failure)
         cell.report_contract_skew error if failure.code == "protocol"
 
         raise error

data/lib/hot_cell/failures.rb

@@ -22,16 +22,18 @@ module HotCell
   # failure into a permanent one.
   class TransientFailure < StandardError; end
 
-  # Extended onto every exception the client raises, so an application can read the failure's code,
-  # cause and permanence without parsing the message — and rescue HotCell::Verdict itself, whatever
-  # classes the registration injected.
-  module Verdict
-    attr_reader :hot_cell_failure
+  class Failure
+    # Extended onto every exception the client raises, so an application can read the failure's code,
+    # cause and permanence without parsing the message — and rescue HotCell::Failure::Exception itself,
+    # whatever classes the registration injected.
+    module Exception
+      attr_reader :hot_cell_failure
 
-    def self.wrap(error, failure)
-      error.extend(self)
-      error.instance_variable_set(:@hot_cell_failure, failure)
-      error
+      def self.wrap(error, failure)
+        error.extend(self)
+        error.instance_variable_set(:@hot_cell_failure, failure)
+        error
+      end
     end
   end
 end

data/lib/hot_cell/install/Dockerfile.tt

@@ -1,4 +1,4 @@
-# The cell's image. HotCell installed this file once; it is yours to customize, and nothing inherits
+# The cell's image. Hot Cell installed this file once; it is yours to customize, and nothing inherits
 # from a published base image — this is the whole recipe.
 #
 # A cell carries a Ruby runtime and every gem in its loaded graph, all inside the blast radius, so treat

data/lib/hot_cell/log_subscriber.rb

@@ -28,7 +28,7 @@ module HotCell
         "  HotCell (#{duration_ms}ms) " + JSON.generate({
           cell: payload[:cell],
           operation: payload[:operation],
-          code: payload[:code] || ("ok" unless payload[:exception]),
+          code: payload[:code],
           exception: payload[:exception]&.first,
           cause: payload[:cause],
           perform_ms: payload[:perform_ms],

data/lib/hot_cell/transport.rb

@@ -13,9 +13,9 @@ module HotCell
       # `timeout` covers the answer and not the connection. On Linux a blocking `connect` to a Unix socket waits
       # in the kernel while the listener's backlog is full, which is where a supervisor that stops calling
       # `accept` leaves it. `UNIXSocket.new` does not wait: Ruby opens every socket non-blocking and takes the
-      # kernel's EAGAIN for a connection in progress, so it returns a socket that never connected, the send
-      # fails with ENOTCONN, and the caller gets `unavailable` at once. That is Ruby's behavior rather than
-      # this gem's, so ControlTimeoutTest holds it.
+      # kernel's EAGAIN for a connection in progress, so it returns a socket that never connected. The send
+      # fails with ENOTCONN, which `deliver` ignores, then the read fails with EINVAL, and the caller gets
+      # `unavailable` at once. That is Ruby's behavior rather than this gem's, so ControlTimeoutTest holds it.
       #
       # If Ruby ever starts waiting, `connect_nonblock` plus `wait_writable` against a deadline would bound the
       # call only by spinning: on Linux an unconnected Unix socket is always writable, so it retries EAGAIN until
@@ -39,9 +39,12 @@ module HotCell
         # then fail while the answer is already waiting on the socket. So this ignores the failed send, and
         # `receive` reads the answer. If the peer closed without an answer, `receive` reports that the
         # supervisor is gone.
+        #
+        # Linux fails that send with EPIPE or ECONNRESET. macOS usually does too, but answers ENOTCONN when the
+        # close lands while its kernel is copying the request in, between checking the socket and queueing.
         def deliver(connection, line, descriptors)
           connection.send_message line, descriptors: descriptors
-        rescue Errno::EPIPE, Errno::ECONNRESET
+        rescue Errno::EPIPE, Errno::ECONNRESET, Errno::ENOTCONN
           nil
         end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotcell-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -38,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.1'
 description: |
-  Call operations that run in a HotCell container. Register a cell, subclass HotCell::Client to name
+  Call operations that run in a Hot Cell container. Register a cell, subclass HotCell::Client to name
   an operation, and call it with open file descriptors and a payload. Failures arrive classified as
   permanent or transient, as exception classes your application supplies.
 email:
@@ -71,8 +71,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
-  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
+  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'
@@ -90,7 +90,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 an application.
+summary: Call a Hot Cell from an application.
 test_files: []