hotcell-client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6808ab8f7c6d12e3917dca07053e1c1ca88b686f43626b895f96a84e2625611
-  data.tar.gz: ee7b60efeaf1b1baed200abe2bc2756d80b75507259b98171c55e78b652ca1d8
+  metadata.gz: c907b155be1d28cc8ca37320ac22f71689f581390e6aa45e77a5a7e31bce04f3
+  data.tar.gz: cb676888f838068d7b6671df95fc869a9bd5736d04556e0f2b0c9a8352e7e300
 SHA512:
-  metadata.gz: 0135bebaa226693ef7c11f5e34ab1562bf6c58694ffbfb0af7aa3666acdeca05930a814696ed0b7097126deb1b8b3683033e3dead4134cecb12edfce65b20d3f
-  data.tar.gz: 1998e3e48ded09c5a5975574ce4f961652c8f0e6f635ab875dafc8cc2eb0553301c9dc0271386657f6348cc22d80358e29f0961d046b417a1cfbcae0931b86da
+  metadata.gz: d436910383ab67af5a826efd3854441c1c90d28bd792657bd6598c27940e7fffa80b1eb50c421eaba737152b4c93a1dd2d2f29243bb9529762ba25bf699bb26b
+  data.tar.gz: e3e71a17d0f2e152fb8a504c6966a9fcb1addf63dc3e383cfa021e402d9c322221c02545bfea92fa9f467952dd492e0bc8b3bc945bc787853df38c491b2b3998

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
 
@@ -65,25 +66,32 @@ module HotCell
       @on_contract_skew&.call error, self
     end
 
-    # Static, and called once at boot. The cheapest way to catch a client pointed at a cell that does not
-    # carry the operation it wants, which is otherwise an `unsupported` on the first real request.
+    # Static, and called once at boot.
     #
     # 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 two 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_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 +103,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 +137,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".
@@ -150,14 +162,27 @@ module HotCell
                             "every operation that gives a tool a filename will fail with EACCES."
       end
 
-      def warn_about_missing_operations(described)
-        carried = Array(described[:operations])
-        wanted = HotCell.clients.select { |client| client.hotcell == name }
+      # 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
 
-        wanted.reject { |client| carried.include?(client.operation) }.each do |client|
-          HotCell.logger.warn "hotcell #{name}: #{client} wants #{client.operation.inspect} and this cell " \
-                              "carries #{carried.inspect}"
-        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!

data/lib/hot_cell/cells.rb

@@ -60,13 +60,6 @@ module HotCell
       cells.key?(name.to_s)
     end
 
-    # Every HotCell::Client subclass, so a boot check can tell which cell is expected to carry what. This
-    # records what the process has loaded rather than what it has configured, so resetting registrations
-    # leaves it alone: the classes are still defined either way.
-    def clients
-      @clients ||= []
-    end
-
     # Call once at boot, after registering. Warns and carries on; see Cell#describe.
     def describe_cells
       warn_about_group

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.3.0"
   end
 end

data/lib/hot_cell/client.rb

@@ -40,11 +40,6 @@ module HotCell
     class << self
       include Declarations
 
-      def inherited(subclass)
-        super
-        HotCell.clients << subclass
-      end
-
       def hotcell(name = nil)
         return inherited_value(:@cell_name) if name.nil?
 

data/lib/hot_cell/install/Dockerfile.tt

@@ -4,9 +4,21 @@
 # A cell carries a Ruby runtime and every gem in its loaded graph, all inside the blast radius, so treat
 # this file as a budget rather than an inventory. Which tools it holds is what decides its blast radius.
 
+# The base image. This tag is mutable: `ruby:3.4-slim` moves as Debian and Ruby publish patches, so a
+# clean build is only as reproducible and as patched as the tag on the day it runs. Build with
+# `docker build --pull` to always take the newest patched base. If you also need to name the exact image
+# you shipped, pin a digest (`FROM ruby:${RUBY_VERSION}-slim@sha256:…`) and refresh it on a schedule; the
+# image scan in CI is what catches a base that has drifted into known-vulnerable either way.
 ARG RUBY_VERSION=3.4
 FROM ruby:${RUBY_VERSION}-slim
 
+# Apply Debian's pending security patches. `--pull` takes the newest base tag, and the tag can still be
+# behind an advisory that is already in `trixie-security`, because only a rebuild by docker-library/ruby
+# moves it. Upgrading here makes the image's patch level its own rather than upstream's release cadence,
+# and it is what keeps the image scan in CI passing on a fixable vulnerability the base has not picked up
+# yet. It costs a layer and a little build time on every build.
+RUN apt-get update && apt-get upgrade -y --no-install-recommends && rm -rf /var/lib/apt/lists/*
+
 # Install the tools and libraries your operations run — and nothing else. For example:
 #
 # RUN apt-get update && \
@@ -25,14 +37,28 @@ RUN mkdir -p /run/hotcell/cell /hotcell/operations && chown -R hotcell:hotcell /
 
 # HOME is /tmp because the cell's user has no home directory, and bundler wants one. A worker replaces
 # it with its slot's home before it serves anything.
+#
+# OpenMP sizes its thread pool from the host's core count, and a `cpus:` quota does not lower it, so an
+# unbounded libvips or ImageMagick asks a 98-core host for 98 threads, each with an 8MB stack.
+# `RLIMIT_DATA` charges those stacks, and libgomp calls `exit(1)` on the first `pthread_create` it cannot satisfy. Match
+# OMP_NUM_THREADS to the container's `cpus:`: the number follows the allocation rather than being 2.
+# OMP_THREAD_LIMIT bounds a library that raises the count itself, which is what ImageMagick does.
 ENV HOME=/tmp \
     BUNDLE_PATH=/hotcell/bundle \
     BUNDLE_WITHOUT=development \
+    OMP_NUM_THREADS=2 \
+    OMP_THREAD_LIMIT=8 \
     HOTCELL_OPERATIONS=/hotcell/operations \
     HOTCELL_DIR=/run/hotcell/cell
 
 WORKDIR /hotcell
 
+# For a reproducible dependency graph, commit a Gemfile.lock next to the Gemfile so a clean build resolves
+# the exact gems the lockfile names rather than whatever the sources offer that day. Generate it for the
+# platform you deploy on — e.g. from a macOS checkout, `bundle lock --add-platform x86_64-linux` so the
+# Linux image accepts it — and build frozen (`bundle install --frozen`, or set `BUNDLE_FROZEN=true`) to
+# refuse a Gemfile that has drifted from the lockfile. Left off by default so a freshly installed scaffold
+# builds before you have generated a lockfile.
 COPY --chown=hotcell:hotcell Gemfile* ./
 USER hotcell
 RUN bundle install
@@ -46,6 +72,13 @@ COPY operations/ /hotcell/operations/
 # root once the build is done. `read-only: true` covers this as well, and this holds without it.
 USER root
 RUN chown -R root:root /hotcell && chmod -R go-w /hotcell
+
+# Strip the setuid and setgid bits off every binary the image carries (mount, umount, su, … from the base,
+# plus anything a RUN above installed). The cell runs as an unprivileged user under `--cap-drop ALL` and
+# `--security-opt no-new-privileges`, which already make these gadgets inert; removing the bits keeps a
+# security image from shipping escalation tools it never uses. As the last root step it covers everything
+# built above it. `-xdev` stays on the image's own filesystem; `chmod a-s` clears both bits.
+RUN find / -xdev -type f -perm /06000 -exec chmod a-s {} +
 USER hotcell
 
 # Probes the supervisor's control socket from inside the container, where network: none does not apply.

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.3.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.3.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.3.0/hotcell-client
+  changelog_uri: https://github.com/basecamp/hotcell/blob/v0.3.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/basecamp/hotcell/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []