hotcell-core 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b90b3c31e988d71fe6f9b1da6c1e727d8c25b934c5085757367fe6e38ffd5aef
-  data.tar.gz: d8eed61e4eeb2d52fe65571ff75b34ff0f73d37ef96c615ec5ab88b7e4d64696
+  metadata.gz: 8891b08ef8f6bea20b5d0046b865792da18374918fd310d1c521eda6c20b5cac
+  data.tar.gz: fe246492b615e044c9762b629de4082f4ac88167a1cedc1b07e13cf235611aae
 SHA512:
-  metadata.gz: 5b8e87d2713d7d8aae5091a469f3a16be1a1dc860e37c4a0b40aa2b3819a1ee3336f7807e88cbb4ae35892f4a6ad5ad892a3c239a6f4928108ecd584946d1d19
-  data.tar.gz: 16ea6b1a37ab997e25d4553f697a6fd390b3b4dbe6869a6b703e0bccf1a1a8467fb14e95921e19c0125e48462aecc4ac578214729573106d4f00e5c0a8ac509c
+  metadata.gz: 0d8e8e358a731b951f94716eec4793aca4f7595213c12b7ebbff89079eef01a205812fe87a4ddac00ed428e8a99412ee81c2bc4812efffbaeab0854da43573e3
+  data.tar.gz: 7b349aff2ee4ccf6e48a3d6545923285337c8b59c00016dd1416ea55f18f5a3b5b7e9786197febc5865bdc07702cf45574461af0717449984074d77e6a2dc368

data/lib/hot_cell/codes.rb

@@ -47,9 +47,9 @@ module HotCell
     # updated by a deploy, so an application that ships a client for a new operation before anybody reboots
     # the cell gets `unsupported` at one hundred percent for as long as that takes.
     #
-    # The two mistakes are not symmetrical. Retrying a caller's typo costs some work and shows up in the
-    # `unsupported` rate and in the client's boot-time warning. Recording a deploy window as permanent
-    # condemns every blob uploaded during it, and needs a hand-written backfill to undo.
+    # The two mistakes are not symmetrical. Retrying a caller's typo costs some work, and it says which
+    # operation in the refusal `worker.rb` writes and in the `unsupported` rate. Recording a deploy window
+    # as permanent condemns every blob uploaded during it, and needs a hand-written backfill to undo.
 
     # `killed` splits on what the worker hit, because a caller cannot otherwise tell a decompression
     # bomb from a slow afternoon. Size and memory are properties of the input, so the same bytes will
@@ -79,6 +79,18 @@ module HotCell
     # from somewhere it cannot see: a cgroup OOM kill chosen on aggregate pressure across concurrent workers,
     # or one worker signalling another — they share a uid, and nothing stops that. Attributing either to the
     # input this worker happened to be holding condemns a file for something it did not do.
+    #
+    # So the supervisor never infers either of them from a signal. They are decided in the worker, which is
+    # the process that holds the request: `memory` when it catches NoMemoryError itself, and `fsize` when a
+    # write of its own returns EFBIG. See Worker#disarm_file_size_signal for why the file-size verdict has
+    # to be earned that way rather than read off a wait status.
+    #
+    # That is a narrower guarantee than "a permanent verdict cannot be forged", and the difference matters.
+    # It removes the supervisor as an instrument: a sibling's signal no longer travels through a wait status
+    # into someone else's blob. It does nothing about a cell that has been compromised outright and answers
+    # a connection itself — `from_wire` believes a `permanent` boolean off the wire, and a worker that stole
+    # `work.sock` writes whatever it likes. That is the socket-theft residual `docs/DESIGN.md` records, and
+    # it is not closed here.
     PERMANENT_BY_CAUSE = {
       FSIZE    => true,
       MEMORY   => true,

data/lib/hot_cell/core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HotCell
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/hot_cell/failure.rb

@@ -15,19 +15,24 @@ module HotCell
   class Failure
     MAX_MESSAGE_BYTES = 512
 
-    attr_reader :code, :message, :error_class, :cause, :signal
+    attr_reader :code, :message, :error_class, :cause, :signal, :stderr
 
-    # Every field is sanitized, not only the message. All five arrive from the wire on the client side, so
-    # all five carry whatever the peer put there — and they travel further than the message does, into
+    # Every field is sanitized, not only the message. All of them arrive from the wire on the client side,
+    # so all of them carry whatever the peer put there — and they travel further than the message does, into
     # `to_s`, into the `perform.hot_cell` event, and into whatever a subscriber writes down. `code` in
-    # particular is the field applications store. Scrubbing one and not the other four left the same
-    # poisoned row the scrub exists to prevent, reachable through a different key.
-    def initialize(code:, permanent: nil, message: nil, error_class: nil, cause: nil, signal: nil)
+    # particular is the field applications store. Scrubbing one and not the rest left the same poisoned row
+    # the scrub exists to prevent, reachable through a different key.
+    def initialize(code:, permanent: nil, message: nil, error_class: nil, cause: nil, signal: nil,
+                   stderr: nil)
       @code = self.class.sanitize(code).to_s
       @cause = self.class.sanitize(cause)
       @signal = self.class.sanitize(signal)
       @error_class = self.class.sanitize(error_class)
       @message = self.class.sanitize(message)
+
+      # The tail, because this is a transcript and its last line is the one that ended the request. Every
+      # other field is one message, where the head is what matters.
+      @stderr = self.class.sanitize(stderr, keep: :tail)
       @permanent = permanent.nil? ? Codes.permanent?(@code, cause: @cause) : permanent
     end
 
@@ -40,11 +45,15 @@ module HotCell
     # `permanent` is the exception and survives, because compact drops only nil.
     def to_h
       { code: code, permanent: permanent? }
-        .merge(cause: cause, signal: signal, class: error_class, message: message).compact
+        .merge(cause: cause, signal: signal, class: error_class, message: message, stderr: stderr).compact
     end
 
+    # `one_line` rather than raw interpolation: `to_s` becomes the exception message an application logs, and
+    # a transcript ends in a newline — so a peer that put newlines in one writes extra lines into that log.
+    # The attribute keeps the raw text.
     def to_s
-      [ code, cause, error_class, message ].compact.join(": ")
+      text = [ code, cause, error_class, message ].compact.join(": ")
+      stderr ? "#{text} (#{self.class.one_line(stderr)})" : text
     end
 
     class << self
@@ -73,14 +82,31 @@ module HotCell
         end
 
         new code: wire[:code], permanent: permanent, cause: wire[:cause], signal: wire[:signal],
-            error_class: wire[:class], message: wire[:message]
+            error_class: wire[:class], message: wire[:message], stderr: wire[:stderr]
+      end
+
+      # For a message that is about to be written as one line of a log. `sanitize` leaves CR and LF alone,
+      # which is right for a message an application stores or re-raises, but a peer that puts a newline in
+      # one writes a second log line of its own — formatted and indented like the real ones. Escape them,
+      # and the rest of the control characters with them.
+      def one_line(text)
+        sanitize(text)&.gsub(/[[:cntrl:]]/) { |character| character.dump[1..-2] }
       end
 
-      def sanitize(message)
+      # `keep: :tail` is for a captured stream rather than a message, and it is load-bearing on `from_wire`:
+      # a cell this client does not trust can fill that field to the response limit, and head-truncating
+      # there hands the caller the noise a decoder printed first instead of the fatal that ended it.
+      def sanitize(message, keep: :head)
         return nil if message.nil?
 
-        String(message).dup.force_encoding(Encoding::UTF_8)
-          .scrub("").byteslice(0, MAX_MESSAGE_BYTES).scrub("")
+        text = String(message).dup.force_encoding(Encoding::UTF_8).scrub("")
+        text = if keep == :tail && text.bytesize > MAX_MESSAGE_BYTES
+          text.byteslice(text.bytesize - MAX_MESSAGE_BYTES, MAX_MESSAGE_BYTES)
+        else
+          text.byteslice(0, MAX_MESSAGE_BYTES)
+        end
+
+        text.scrub("")
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotcell-core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -10,12 +10,9 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  HotCell runs untrusted media conversion in an unprivileged sibling container with no network,
-  reached over a Unix socket that carries file descriptors rather than paths or bytes.
-
-  This gem holds what both sides must agree on: the request and response format, SCM_RIGHTS
-  marshalling, descriptor access-mode verification, payload validation, and the error taxonomy.
-  It performs no I/O of its own and loads no media library.
+  The wire protocol between an application and a HotCell container: the request and response format,
+  file descriptor passing over SCM_RIGHTS, payload validation, and the error taxonomy. Both
+  hotcell-client and hotcell-server depend on it. Install one of those rather than this.
 email:
 - mike@37signals.com
 executables: []
@@ -46,8 +43,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/basecamp/hotcell
-  source_code_uri: https://github.com/basecamp/hotcell/tree/v0.1.0/hotcell-core
-  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-core
+  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: []