hotcell-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6808ab8f7c6d12e3917dca07053e1c1ca88b686f43626b895f96a84e2625611
-  data.tar.gz: ee7b60efeaf1b1baed200abe2bc2756d80b75507259b98171c55e78b652ca1d8
+  metadata.gz: 62be0a0a7b86a0273cfdfbe7ed7cd04460e536aeb3af1a03b08b944930c18082
+  data.tar.gz: cf6ffc9e65616d8cb89219f57e8273ecd8a7f8d47b5fc85db74f6014ff1e61bd
 SHA512:
-  metadata.gz: 0135bebaa226693ef7c11f5e34ab1562bf6c58694ffbfb0af7aa3666acdeca05930a814696ed0b7097126deb1b8b3683033e3dead4134cecb12edfce65b20d3f
-  data.tar.gz: 1998e3e48ded09c5a5975574ce4f961652c8f0e6f635ab875dafc8cc2eb0553301c9dc0271386657f6348cc22d80358e29f0961d046b417a1cfbcae0931b86da
+  metadata.gz: 93e74a6462bf95bed04585d87588df0916eaadb4eaab24b37966c8c7266f0051a5a9c8de6c825a542c54a0481ae885799bf56b892f7d184eaf99ee83895ff6ee
+  data.tar.gz: 99571523cc72ad1845a95dcab86dab7f9de917673543832d7abf591e182ec927dd77c542640fe9b94777eb39fcdbf8e7746e147f6fd41571b3f00251870d0646

data/lib/hot_cell/cell.rb

@@ -28,6 +28,7 @@ module HotCell
       @on_contract_skew = on_contract_skew
       @transport = transport
 
+      verify_bounds!
       verify_classification!
     end
 
@@ -71,19 +72,28 @@ module HotCell
     # Boot must not fail when a cell does not answer. A cell that is down at app boot is a degraded
     # deployment rather than a broken one, and an application that refuses to start because its thumbnail
     # cell is restarting is worse than one that serves placeholders. So this warns and carries on.
+    #
+    # Nor when a cell answers something this client cannot read. The three warnings below reach into the
+    # description without checking types, so a cell that sends the wrong ones raises here — and the README
+    # calls `describe_cells` from `after_initialize`, where that is not a failed check but an application
+    # that does not boot. The process that wrote the description is the one that runs untrusted content.
+    # So rescue: returning nil is what an unreachable cell already returns, and every caller handles it.
     def describe
       return nil unless enabled?
 
       response = control(DESCRIBE)
-      unless response.ok?
-        HotCell.logger.warn "hotcell #{name}: #{unreachable_because response.failure}"
-        return nil
-      end
+      return warn_unreachable(response.failure) unless response.ok?
 
-      warn_about_timeout response.result
-      warn_about_missing_operations response.result
-      warn_about_group_skew response.result
-      response.result
+      response.result.tap do |described|
+        warn_about_timeout described
+        warn_about_missing_operations described
+        warn_about_group_skew described
+      end
+    rescue StandardError => error
+      HotCell.logger.warn "hotcell #{name}: this cell's description could not be read and is being " \
+                          "ignored (#{error.class}: #{Failure.one_line error.message}). Boot continues; " \
+                          "nothing it carries is assumed."
+      nil
     end
 
     def metrics
@@ -95,13 +105,18 @@ module HotCell
       # that admits a caller. EACCES therefore means one thing, and it is worth saying rather than leaving an
       # operator to read "could not describe the cell" as "the cell is down". Every other failure reads that
       # way correctly, because a restarting accessory is the common one.
+      def warn_unreachable(failure)
+        HotCell.logger.warn "hotcell #{name}: #{unreachable_because failure}"
+        nil
+      end
+
       def unreachable_because(failure)
         if failure.error_class == "Errno::EACCES"
           "this process may not open the cell's socket. Both sides share a group, and this one is in " \
           "#{Process.groups.sort.inspect}. Add the cell's gid to this container (Kamal: `group-add` under " \
           "the role's `options:`)."
         else
-          "could not describe the cell (#{failure})"
+          "could not describe the cell (#{Failure.one_line failure})"
         end
       end
 
@@ -124,10 +139,9 @@ module HotCell
         return if needed.nil? || timeout.nil? || timeout >= needed
 
         HotCell.logger.warn "hotcell #{name}: this client waits #{seconds timeout} and the cell says it may " \
-                            "take #{seconds needed} to answer (queue_wait #{seconds described[:queue_wait]} + " \
-                            "deadline #{seconds described[:deadline]} + the time to kill and reply), so a " \
-                            "saturated cell will arrive here as a transport failure rather than as its own " \
-                            "verdict. Deliberate on a synchronous path; a mistake for a background job."
+                            "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 " \
+                            "path; a mistake for a background job."
       end
 
       # The cell reports seconds as floats, and "41.0s" is a worse sentence than "41s".
@@ -160,6 +174,29 @@ module HotCell
         end
       end
 
+      # A `nil` timeout reaches `Transport::Socket#receive` as `deadline: nil`, and reading with no deadline
+      # blocks: a cell that accepts the connection and then never answers holds this caller for good. At
+      # boot that is an application that never finishes starting, with no exception and nothing to rescue.
+      #
+      # Refused at registration rather than defaulted, so that a `timeout:` read from an unset environment
+      # variable says so instead of quietly becoming 30 seconds. Same reason as `verify_classification!`.
+      def verify_bounds!
+        @timeout = bounded!(:timeout, timeout)
+        @control_timeout = bounded!(:control_timeout, control_timeout)
+      end
+
+      # Stored as a Float, because the only thing done with the number is `Clock.now + timeout`. That is
+      # also why `finite?` is part of the test: `10**400` is a positive Integer, and adding it to a clock
+      # gives `Infinity` — a deadline that never passes, which is the wait this refuses.
+      def bounded!(name, value)
+        seconds = Float(value, exception: false)
+        return seconds if seconds&.finite? && seconds.positive?
+
+        raise ConfigurationError,
+              "#{name}: #{value.inspect[0, 60]} does not bound anything, so a cell that never answers " \
+              "would hold this call for as long as it liked. It must be a positive number of seconds."
+      end
+
       def verify_classification!
         return if permanent.nil? || transient.nil?
         return unless transient <= permanent

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 = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/hot_cell/install.rb

@@ -18,8 +18,12 @@ module HotCell
       def call(root, out: $stdout)
         templates.each do |template|
           relative = template.delete_prefix("#{TEMPLATES}/").delete_suffix(".tt")
-          install template, File.join(root, "hotcell", relative), "hotcell/#{relative}", out
+          write File.join(root, "hotcell", relative), "hotcell/#{relative}", out do
+            render template
+          end
         end
+
+        keep_operations root, out
       end
 
       private
@@ -27,12 +31,27 @@ module HotCell
           Dir.glob("#{TEMPLATES}/**/*.tt", File::FNM_DOTMATCH).sort
         end
 
-        def install(template, destination, label, out)
+        # **The directory the generated Dockerfile copies, made here rather than shipped.**
+        #
+        # It used to be a template, `install/operations/.keep.tt`, and a dotfile is exactly what the
+        # gemspec's `Dir["lib/**/*"]` does not match — so the published 0.1.0 carried the directory's only
+        # file nowhere, `COPY operations/` had nothing to copy, and the advertised scaffold could not build.
+        # The checkout's own install test could not see it, because in a checkout the file is simply there.
+        #
+        # An empty file rather than an empty directory, because the application's git is what has to keep
+        # this after a fresh clone, and git tracks no empty directories.
+        def keep_operations(root, out)
+          write File.join(root, "hotcell", "operations", ".keep"), "hotcell/operations/.keep", out do
+            ""
+          end
+        end
+
+        def write(destination, label, out)
           if File.exist?(destination)
             out.puts "   skip  #{label} (already exists)"
           else
             FileUtils.mkdir_p File.dirname(destination)
-            File.write destination, render(template)
+            File.write destination, yield
             out.puts " create  #{label}"
           end
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotcell-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -38,13 +38,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.1'
 description: |
-  The application side of HotCell. Register the cells a deployment runs, subclass HotCell::Client to
-  name one, and call it with descriptors and a payload.
-
-  The client owns everything a caller needs to respond correctly to a cell that is saturated,
-  restarting, or absent: the classification of every error into permanent and transient, the
-  exception classes an application injects for each, and instrumentation through
-  ActiveSupport::Notifications.
+  Call operations that run in a HotCell 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:
 - mike@37signals.com
 executables: []
@@ -71,8 +67,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/basecamp/hotcell
-  source_code_uri: https://github.com/basecamp/hotcell/tree/v0.1.0/hotcell-client
-  changelog_uri: https://github.com/basecamp/hotcell/blob/v0.1.0/CHANGELOG.md
+  source_code_uri: https://github.com/basecamp/hotcell/tree/v0.2.0/hotcell-client
+  changelog_uri: https://github.com/basecamp/hotcell/blob/v0.2.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/basecamp/hotcell/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []