hotcell-server 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53155a8007bc4aca15485dd336ec9a4f74942a0315d14b605e3f05b224d68f01
-  data.tar.gz: bfb05888e741fb289abb075712894900b022c16d32affd5f21d53a44f2f437da
+  metadata.gz: 7f09004467e489b37a062a04d9f4e4f418cfa91de46cab560316de61d624be2b
+  data.tar.gz: 06126ba9b14c71d06c8de92639fe25471eb61ab298561811dd059193d0476f98
 SHA512:
-  metadata.gz: d9a0fe3431faabd5b3f19fdac5afd4f5346e85dc4513598242253134d7b392352d15de9ff9debab298103997ac1a28938c1cb1cbb04db2f80121e02dd2fe72c9
-  data.tar.gz: 8e35674f33719a62d26a4a269a19017deb9e7de30b8afbf5802a22cba0db6abd5a9348f90cb81e7691dd9f8bb6f3db01d1c8e7e0e0ba4db106a9a7547ce6788a
+  metadata.gz: 652224e5285628af8183e8e11b9195c776072caff19f6e99bab4072278838bc960ec47c14a6634fc24ef91e83a0e45579037e4b2716fa8da6c79cca07723a581
+  data.tar.gz: f01b60a20606eae2706953fb46928801a304c0d8b3b1945018c17425c8189fd2419c11d45ab29a492906c7c164650cbd587778c3d2adb960c728de3f8281ea87

data/README.md

@@ -1,3 +1,3 @@
 # hotcell-server
 
-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/configuration.rb

@@ -83,7 +83,7 @@ module HotCell
     # Derived here rather than reassembled in the client: a client adding up `queue_wait + deadline` plus its
     # own guess at the kill-to-answer step cannot follow a change to any of them, and the error points the
     # unsafe way — the client believes its timeout is generous and takes a transport failure instead of the
-    # cell's verdict. A stage added later that costs a caller time belongs in this sum.
+    # cell's answer. A stage added later that costs a caller time belongs in this sum.
     def answer_within
       queue_wait + limits.deadline + KILL_GRACE
     end

data/lib/hot_cell/counters.rb

@@ -18,6 +18,7 @@ module HotCell
   class Counters
     def initialize
       @started_at = Clock.now
+      @start_time = Time.now.to_f
       @requests = Hash.new(0)
       @killed_by = Hash.new(0)
       @cancelled = 0
@@ -42,8 +43,8 @@ module HotCell
     end
 
     def to_h(running: 0, queued: 0)
-      { uptime_s: (Clock.now - @started_at).round, running: running, queued: queued,
-        queue_high_water: @queue_high_water, requests: @requests, killed_by: @killed_by,
+      { start_time_s: @start_time, uptime_s: (Clock.now - @started_at).round, running: running,
+        queued: queued, queue_high_water: @queue_high_water, requests: @requests, killed_by: @killed_by,
         cancelled: @cancelled }
     end
   end

data/lib/hot_cell/operation.rb

@@ -75,7 +75,7 @@ module HotCell
       # does not survive fork and the child waits on a pool with no threads. Not the first worker — every
       # worker. A later change that pre-warms the pool to save the fork cost is exactly what this forbids.
       #
-      # Note that a hotcell forks per request, continuously, so "before the fork" and "at boot" are not
+      # Note that a cell forks per request, continuously, so "before the fork" and "at boot" are not
       # the same moment the way they are in Puma. This runs once.
       def before_fork(&block)
         return collected(:@before_fork) if block.nil?
@@ -147,7 +147,7 @@ module HotCell
     # streams in full and hands them over at exit, so slicing afterwards bounded the Strings this method
     # returns and nothing else: an input that makes a tool print gigabytes of diagnostics had already
     # cost gigabytes of this worker's address space, and took RLIMIT_DATA with it — arriving as a `memory`
-    # verdict, which is permanent, for a document whose only crime was being noisy.
+    # failure, which is permanent, for a document whose only crime was being noisy.
     # `pass` hands the tool a set of the worker's own descriptors — an input to read, an output to write —
     # at their existing fd numbers, so the tool reaches them at `Descriptor#fd_path` — `/dev/fd/N`, or the
     # file's own path on macOS, where opening `/dev/fd/N` would share the worker's offset — and no

data/lib/hot_cell/server/errors.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module HotCell
-  # What an operation raises to choose its own verdict. An operation may also declare the library
+  # What an operation raises to choose its own failure. An operation may also declare the library
   # exceptions that mean the same thing, with `unreadable Vips::Error`.
   class OperationError < StandardError; end
 

data/lib/hot_cell/server/version.rb

@@ -2,6 +2,6 @@
 
 module HotCell
   module Server
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
   end
 end

data/lib/hot_cell/supervisor.rb

@@ -427,7 +427,7 @@ module HotCell
       end
 
       # A worker can die between the fork and this write. Answering rather than raising is what keeps one dead
-      # worker from taking the whole cell down with it, and the caller gets a transient verdict either way.
+      # worker from taking the whole cell down with it, and the caller gets a transient failure either way.
       def dispatch(child, connection, queued_ms)
         child.dispatched connection, configuration.limits.deadline, at: Clock.now
 
@@ -784,7 +784,7 @@ module HotCell
       end
 
       def finish(child, code, cause = nil)
-        counters.record outcome_code(code)
+        counters.record reported_code(code)
         counters.record_kill cause if reported_cause?(code, cause)
         child.finished
         discard child
@@ -792,7 +792,7 @@ module HotCell
         retire child if configuration.retire?(child.served)
       end
 
-      # The outcome code rides an untrusted worker report and becomes both a counter key and a Symbol, so it
+      # The code rides an untrusted worker report and becomes both a counter key and a Symbol, so it
       # is bounded to a code this cell mints before either happens. Without this a report of `code: []` raised
       # NoMethodError on `to_sym` past `apply_report`'s rescue and took the cell down, and a stream of unique
       # strings grew the counters without bound. An unknown code is recorded, so a misreporting worker is
@@ -801,7 +801,7 @@ module HotCell
       # It is checked against the known causes rather than passed through, because `record_kill` interns it
       # as a symbol and an unchecked one is an unbounded symbol table keyed by whatever a tool decides.
       def reported_cause?(code, cause)
-        outcome_code(code) == Codes::KILLED && cause.is_a?(String) &&
+        reported_code(code) == Codes::KILLED && cause.is_a?(String) &&
           Codes::PERMANENT_BY_CAUSE.key?(cause)
       end
 
@@ -810,7 +810,7 @@ module HotCell
         reported if reported.is_a?(String) && Registry.lookup(reported)
       end
 
-      def outcome_code(reported)
+      def reported_code(reported)
         return reported if reported.is_a?(String) && (reported == "ok" || Codes.known?(reported))
 
         "unknown"
@@ -853,7 +853,7 @@ module HotCell
         now = Clock.now
 
         @children.each_value.select { |child| child.lingering?(now, Configuration::KILL_GRACE) }.each do |child|
-          # The latch rather than a verdict: a lingering child is never busy, so no caller hears this cause.
+          # The latch rather than an answer: a lingering child is never busy, so no caller hears this cause.
           child.killed_for = Codes::CRASHED
 
           kill_group child
@@ -968,7 +968,7 @@ module HotCell
       end
 
       # A killed worker cannot report its own death, because the deadline KILL is enforced by a signal. So
-      # the supervisor holds its copy of every dispatched connection and writes the verdict itself. Without
+      # the supervisor holds its copy of every dispatched connection and writes the answer itself. Without
       # this the cold side sees a bare end of stream and cannot tell a limit
       # breach from a crash.
       # A worker still holding a connection at reap time never answered: it reports itself idle after writing,
@@ -978,10 +978,10 @@ module HotCell
       # supervisor sent, and it is the one thing here that knows why a worker died. Everything else is a
       # wait status, which says how — and workers share a uid, so any signal in one may have come from a
       # sibling rather than from the kernel. Reading XFSZ, SEGV, ABRT or TRAP as this request's file size or
-      # memory let one compromised worker write a permanent verdict against another request's unrelated
+      # memory let one compromised worker write a permanent failure against another request's unrelated
       # input, which Active Storage then kept. `Codes` already stated the rule this broke.
       #
-      # The verdicts themselves are not gone, they moved to where they can be earned: the worker answers
+      # The failures themselves are not gone, they moved to where they can be earned: the worker answers
       # `memory` when it catches NoMemoryError and `fsize` when a write of its own returns EFBIG, on the
       # connection it is holding. See Worker#disarm_file_size_signal.
       #
@@ -1001,7 +1001,7 @@ module HotCell
                                    signal: signal_name(status), duration_ms: Clock.ms_since(child.dispatched_at),
                                    **captured
 
-        # The capture rides the verdict as well as the log line, so an application logs
+        # The capture rides the failure as well as the log line, so an application logs
         # `killed: crashed (libgomp: ...)` rather than a bare `crashed`. Additive on the wire: `from_wire`
         # reads named keys, so an old client ignores the field and a new one against an old cell meets nil.
         answer child.connection,

data/lib/hot_cell/test_operations.rb

@@ -187,7 +187,7 @@ module HotCell
 
     # A tool spawn that fails because the host is out of memory. fork raises Errno::ENOMEM under host
     # pressure, before the tool has read a byte of the input, so this is the cell having a bad moment
-    # rather than a decompression bomb — and it must not be recorded as a permanent memory verdict.
+    # rather than a decompression bomb — and it must not be recorded as a permanent `memory` failure.
     class StarvedSpawn < HotCell::Operation
       operation "test.starved_spawn"
 
@@ -200,7 +200,7 @@ module HotCell
       operation "test.signals_sibling"
 
       # Workers share a uid and a pid namespace, so one finds another by looking for a process the
-      # supervisor also fathered. This is the reproducer for the forged verdict: nothing here touches the
+      # supervisor also fathered. This is the reproducer for the forged failure: nothing here touches the
       # victim's input, and the victim is holding an unrelated one.
       def perform(_inputs, _outputs, signal:)
         sibling = siblings.first

data/lib/hot_cell/timing.rb

@@ -11,7 +11,7 @@ module HotCell
   # here, when `performing` is called.
   #
   # Phases accumulate as they complete, so a refusal reports the ones that finished before the failure. An
-  # `unreadable` verdict that arrives with no `operation_ms` says exactly where it got to.
+  # `unreadable` failure that arrives with no `operation_ms` says exactly where it got to.
   class Timing
     attr_reader :queued_ms, :started
 

data/lib/hot_cell/worker.rb

@@ -29,7 +29,7 @@ module HotCell
     #
     # A non-zero status for anything unexpected, because the supervisor holds the connection and is the only
     # thing that can answer for a worker that died mid-request. Exiting zero here would leave a caller reading
-    # a closed socket with no verdict at all.
+    # a closed socket with no answer at all.
     #
     # **The one deliberate `rescue Exception` in this repository.** Not for the exit status — Ruby's own handler
     # would also exit non-zero — but for Failure.sanitize. Left to Ruby, a NoMemoryError or a SystemStackError
@@ -67,8 +67,8 @@ module HotCell
       #
       # Catching it makes the kernel fail the offending write with EFBIG rather than killing the process,
       # and that error return is what a signal is not: it is raised by a write this process made, and no
-      # signal any sibling sends produces one. So the verdict below keys on Errno::EFBIG and this handler
-      # does nothing at all. A handler that set so much as a flag the verdict consulted would hand the
+      # signal any sibling sends produces one. So the `fsize` failure below keys on Errno::EFBIG and this handler
+      # does nothing at all. A handler that set so much as a flag that failure consulted would hand the
       # forgery straight back.
       #
       # EFBIG is evidence of this request's own write and not proof of which limit stopped it. A filesystem
@@ -137,7 +137,7 @@ module HotCell
         # transient. Adding it back would condemn a blob for the cell's own bad moment.
         rescue NoMemoryError, MemoryExhausted => error
           response = refuse(Codes::KILLED, error, timing, cause: Codes::MEMORY)
-        # The one place a file-size verdict can be earned. EFBIG comes back from a write this worker made
+        # The one place an `fsize` failure can be earned. EFBIG comes back from a write this worker made
         # past its own RLIMIT_FSIZE, so unlike the signal it cannot arrive from anywhere else.
         rescue Errno::EFBIG => error
           response = refuse(Codes::KILLED, error, timing, cause: Codes::FSIZE)
@@ -229,7 +229,7 @@ module HotCell
       # reads as success. This is the side that knows which one is empty, so it is the side that says so.
       #
       # Transient, for the reason the client's own check is: the commonest way to write nothing is a full
-      # tmpfs, and a full filesystem must never be recorded as a verdict on the document.
+      # tmpfs, and a full filesystem must never be recorded as a permanent failure of the document.
       def unwritten(outputs, written, timing)
         empty = written.each_index.select { |index| written[index].zero? }
 
@@ -295,7 +295,7 @@ module HotCell
       # that off a wait status; it reads the worker's own report now, and only when there is a cause to send,
       # so an ordinary idle report is the two keys it always was.
       #
-      # **This is a metric and not a verdict.** The verdict went to the caller on the work connection before
+      # **This is a metric and not an answer.** The answer went to the caller on the work connection before
       # this line runs. A compromised worker can report a cause its request never had, or withhold one it
       # did, so `killed_by` is what workers said rather than what happened — which is why the supervisor
       # checks the value against the known causes before interning it, and why nothing downstream may treat

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotcell-server
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -15,16 +15,16 @@ 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
 description: |
-  Runs a HotCell container. A supervisor listens on two Unix sockets, forks a worker for each request,
+  Runs a Hot Cell container. A supervisor listens on two Unix sockets, forks a worker for each request,
   and enforces a wall clock deadline and resource limits on it. Write the work as a subclass of
   HotCell::Operation.
 email:
@@ -64,8 +64,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/basecamp/hotcell
-  source_code_uri: https://github.com/basecamp/hotcell/tree/v1.1.0/hotcell-server
-  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-server
+  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'
@@ -83,7 +83,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: 'Run a HotCell: the supervisor, the worker, and the operation API.'
+summary: 'Run a Hot Cell: the supervisor, the worker, and the operation API.'
 test_files: []