hotcell-core 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6b2888231865d0473516c75ab8b1caf8fe162d414b5d63978dad521e0cf65e5
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: e60aebb6474f67f6a35f01d9fe1e3a686c422a073e11ebf785af0816ade80e79
+  data.tar.gz: eb13e25de57e23ff35d57fe100926cd64c11ecad18af96104dd3864d2246411b
 SHA512:
-  metadata.gz: ba01bcb50b70fb26fd0c01e5e1a7d60fac57cc7d965638289fd8a603f1edd4294a21786305231e022628f9211e4b2d51da66483d52f183f898343e7a27550800
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: 0c0373bb9b2831d65e5fce1b02c7cb0ede24eed5a3d64144d905abbd93d72a7dcbf3d46250acb24caf195e1e1f9e0a530fa07ef2845c1ccba2118aed4f4e1aa2
+  data.tar.gz: a087aedd5855c87b413c53085e23d9d579a59176bc9453d1e07e4712592d1c1405f8939d42c6123ae3fa5bcf9b50ad3d0112353d3adba359a7814d55a0e0b10f

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 37signals, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

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

data/lib/hot_cell/clock.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module HotCell
+  # Monotonic, because every duration here is reported to a caller that will alarm on it, and a clock
+  # that can step backwards produces negative latencies during an NTP correction.
+  module Clock
+    class << self
+      def now
+        Process.clock_gettime Process::CLOCK_MONOTONIC
+      end
+
+      def ms_since(at)
+        ((now - at) * 1000).round(2)
+      end
+    end
+  end
+end

data/lib/hot_cell/codes.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module HotCell
+  # Every failure carries a code and a `permanent` flag, and `permanent` is the only distinction that
+  # changes what a caller must do.
+  #
+  # Terminal means the same request fails the same way until the input or the code changes — not until
+  # the load or the deployment changes. A permanent failure may be recorded against a blob and served
+  # from a cache. A non-permanent one must be retried and must never be written down.
+  #
+  # The flag travels on the wire, set by the side that knows, rather than being derived by each caller
+  # from the code. That is what makes a code added later safe: an old client will not recognise it but
+  # will still dispose of it correctly.
+  module Codes
+    PERMANENT = {
+      "unreadable"  => true,   # the input could not be decoded — the operation said so explicitly
+      "invalid"     => true,   # malformed request, or a descriptor that failed its access-mode check
+      "failed"      => false,  # the operation raised something nobody classified — see below
+      "unsupported" => false,  # this cell does not carry that operation — see below
+      "protocol"    => false,  # version mismatch, which heals when the accessory reboots
+      "capacity"    => false,  # the queue is full
+      "unavailable" => false,  # no connection, or a connection closed with no response
+      "timeout"     => false,  # the client's own deadline fired
+    }.freeze
+
+    # **`failed` is what an unclassified exception becomes, so it cannot be permanent.**
+    #
+    # A worker rescues StandardError around the whole request and calls it `failed`. Errno::ENOSPC is a
+    # StandardError, and so are EMFILE, EIO, ENOENT and ENOMEM. A shared tmpfs filled by concurrent requests,
+    # a full disk under the caller's own output, a descriptor table exhausted by load, a fork that cannot get
+    # memory under host pressure, a tool missing during a broken deploy — every one of those raises inside
+    # staging or writeback and arrives here. ENOMEM is the one that looks like the input's fault and is not:
+    # the worker's own out-of-memory, where the input drove it past its limit, is a NoMemoryError, which the
+    # worker classifies `killed`/`memory` instead.
+    #
+    # Terminal meant each of them was written down against a customer's file and served from a cache forever,
+    # for a condition that would have succeeded on retry. Permanence has to be claimed, never inferred from
+    # not knowing: an operation says `unreadable` for an input it could not decode, and the protocol says
+    # `invalid` for a caller that broke its own contract. Everything else is this cell having a bad day.
+    #
+    # The cost of the other mistake is a genuinely broken operation being retried. That is bounded by the
+    # job's attempts, it is visible in the `failed` rate, and it is recoverable.
+
+    # **`unsupported` is transient, and the design document says otherwise.** Its reasoning was that an
+    # unknown *operation* is a caller bug that never heals, where an unknown *version* is a deploy window
+    # that does. That holds for a typo and not for the case that actually happens: an accessory is not
+    # 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.
+
+    # `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
+    # do it again on an idle cell. A deadline is as much a property of the load, and treating it as
+    # permanent means a busy hour permanently condemns whatever was uploaded during it.
+    # `crashed` is the cell's own fault rather than the input's — a worker that died without answering, which
+    # a misconfigured cell does on every request. Recording that against a blob would condemn everything
+    # uploaded during a broken deploy, so it is transient. An older client that has never heard of it still
+    # disposes of it correctly, because `permanent` travels on the wire.
+    #
+    # **A limit this table has never heard of is not permanent, and that default is the point of the table.**
+    # A cell mints these; adding a kill reason to the supervisor without adding a row here used to make it
+    # permanent, silently, and permanent is the answer that cannot be taken back. The names below are
+    # constants so that the two places that mint them cannot spell one the table does not carry.
+    #
+    # Raising instead — the way an unknown *code* raises — would be worse than the bug. `Supervisor#answer_for`
+    # builds its Failure as an argument to `answer`, so the raise would land before that method's rescue, and
+    # neither `reap` nor `drain_signals` nor `run` catches it. A typo would take the whole cell down from the
+    # one path whose job is reporting a dead worker.
+    FSIZE = "fsize"
+    MEMORY = "memory"
+    DEADLINE = "deadline"
+    CRASHED = "crashed"
+
+    # `signal` is the unexplained death, and it is not permanent, because a signal says how a process died and
+    # never why. The supervisor knows it sent SIGKILL for a deadline and says so. Every other signal arrived
+    # 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,
+      DEADLINE => false,
+      CRASHED  => false,
+    }.freeze
+
+    KILLED = "killed"
+
+    class << self
+      def permanent?(code, cause: nil)
+        code = code.to_s
+        return PERMANENT_BY_CAUSE.fetch(cause.to_s, false) if code == KILLED
+
+        PERMANENT.fetch(code) do
+          raise ArgumentError, "unknown error code #{code.inspect}"
+        end
+      end
+
+      def known?(code)
+        code.to_s == KILLED || PERMANENT.key?(code.to_s)
+      end
+    end
+  end
+end

data/lib/hot_cell/connection.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module HotCell
+  # One request per connection: the cold side connects, sends one request with its descriptors, reads
+  # one response line, and closes. The hot side never initiates.
+  #
+  # SOCK_STREAM rather than SOCK_SEQPACKET, and the receiver pays for it. Real message boundaries would
+  # remove the framing problem outright, and Darwin has no AF_UNIX SOCK_SEQPACKET, so a stream socket is
+  # what there is. A stream socket does not promise that one sendmsg arrives as one recvmsg, and the
+  # ancillary data rides on whichever bytes land first. So read to the newline in a loop, and take the
+  # descriptors from whichever recvmsg carried them rather than from the one that completes the line.
+  #
+  # An implementation that assumes one sendmsg is one recvmsg passes every test small enough not to
+  # fragment, which is why this is written down here rather than left to be rediscovered.
+  class Connection
+    CHUNK_BYTES = 4096
+
+    attr_reader :socket
+
+    def initialize(socket)
+      @socket = socket
+    end
+
+    # So that a connection can itself be passed over SCM_RIGHTS. That is how the supervisor hands an
+    # accepted connection to a worker without reading it: the caller's descriptors stay queued on the
+    # connection until somebody calls recvmsg, and the worker is the one who does.
+    def to_io
+      socket
+    end
+
+    # The descriptors ride the first sendmsg and the rest of the line follows as ordinary writes, because a
+    # stream socket does not promise that one sendmsg sends all of it. The return value used to be ignored:
+    # a short send that carried the ancillary data left the receiver holding the descriptors and waiting for
+    # a newline that never came, while this side moved on to waiting for a response. Both ends then sat
+    # until something else timed them out — and the caller's descriptors were installed in the cell either
+    # way, so it is not a case that fails safe.
+    #
+    # Ancillary data goes exactly once. Sending it again with a later chunk would install a second copy of
+    # every descriptor in the receiver.
+    def send_message(line, descriptors: [])
+      sent = if descriptors.empty?
+        socket.sendmsg line
+      else
+        socket.sendmsg line, 0, nil, Socket::AncillaryData.unix_rights(*descriptors.map(&:to_io))
+      end
+
+      write_all line.byteslice(sent..) if sent < line.bytesize
+    end
+
+    # Returns [line, descriptors]. The line is nil when the peer closed without sending anything.
+    #
+    # The caller owns the descriptors and must close every one of them, including any it will not use.
+    # A request that is refused still arrives with its descriptors installed in this process.
+    def receive_message(limit: MAX_REQUEST_BYTES)
+      buffer = "".b
+      descriptors = []
+
+      loop do
+        chunk, _, _, *controls = socket.recvmsg(CHUNK_BYTES, 0, nil, scm_rights: true)
+        descriptors.concat controls.flat_map(&:unix_rights)
+
+        break if chunk.nil? || chunk.empty?
+        buffer << chunk
+        break if buffer.include?("\n")
+
+        raise MessageError, "message passed #{limit} bytes with no newline" if buffer.bytesize > limit
+      end
+
+      [ line_from(buffer, limit), descriptors ]
+    rescue StandardError
+      descriptors.each { |descriptor| descriptor.close unless descriptor.closed? }
+      raise
+    end
+
+    # IO#write already loops until everything is written or it raises, which sendmsg does not.
+    def write_line(line)
+      write_all line
+    end
+
+    # UTF-8 for the same reason receive_message forces it: a socket read comes back ASCII-8BIT, where every
+    # byte is "valid" and nothing downstream can tell a mis-encoded message from a good one. Both directions
+    # should behave the same way, and the one that scrubs is Failure.
+    #
+    # `deadline` is an absolute instant covering the whole line rather than a per-read timeout, because a
+    # per-read one bounds nothing. Waiting for the socket to be readable and then calling a blocking `gets`
+    # meant a peer that sent a single byte inside the timeout and then stopped held the caller until the
+    # cell's own deadline, or forever against a peer that never closed. Returns nil at end of stream, and
+    # raises Timeout when the deadline passes with the line incomplete.
+    def read_line(limit: MAX_RESPONSE_BYTES, deadline: nil)
+      buffer = "".b
+
+      until buffer.end_with?("\n")
+        chunk = read_chunk(deadline)
+
+        if chunk.nil?
+          return nil if buffer.empty?
+
+          raise MessageError, "message ended after #{buffer.bytesize} bytes with no newline"
+        end
+
+        buffer << chunk
+        raise MessageError, "message passed #{limit} bytes with no newline" if buffer.bytesize > limit
+      end
+
+      buffer.force_encoding Encoding::UTF_8
+    end
+
+    def close
+      socket.close unless socket.closed?
+    end
+
+    private
+      def write_all(bytes)
+        socket.write bytes
+      end
+
+      # Returns nil at end of stream. With no deadline this blocks, which is what the cell's own side wants —
+      # it is bounded by the supervisor rather than by a clock here.
+      def read_chunk(deadline)
+        if deadline
+          remaining = deadline - Clock.now
+
+          unless remaining.positive? && socket.wait_readable(remaining)
+            raise ReadTimeout, "the peer stopped mid-message and the deadline passed"
+          end
+        end
+
+        socket.readpartial CHUNK_BYTES
+      rescue EOFError
+        nil
+      end
+
+      def line_from(buffer, limit)
+        return nil if buffer.empty?
+
+        newline = buffer.index("\n")
+        raise MessageError, "message ended after #{buffer.bytesize} bytes with no newline" if newline.nil?
+
+        if newline < buffer.bytesize - 1
+          raise MessageError, "#{buffer.bytesize - newline - 1} bytes follow the message line, and one " \
+                              "connection carries one message"
+        end
+        raise MessageError, "message is #{buffer.bytesize} bytes, over the #{limit} byte limit" if buffer.bytesize > limit
+
+        buffer.force_encoding Encoding::UTF_8
+      end
+  end
+end

data/lib/hot_cell/core/version.rb

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

data/lib/hot_cell/core.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "hot_cell/core/version"
+require "hot_cell/protocol"
+require "hot_cell/errors"
+require "hot_cell/codes"
+require "hot_cell/clock"
+require "hot_cell/naming"
+require "hot_cell/declarations"
+require "hot_cell/payload"
+require "hot_cell/fields"
+require "hot_cell/descriptors"
+require "hot_cell/failure"
+require "hot_cell/request"
+require "hot_cell/response"
+require "hot_cell/connection"

data/lib/hot_cell/declarations.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module HotCell
+  # How a class-level declaration is read back on both sides of the socket.
+  #
+  # `HotCell::Client` and `HotCell::Operation` are the same shape of thing — a class whose body declares what
+  # it is, with a subclass free to override one declaration and inherit the rest. Both needed the same lookup
+  # and both had their own copy of it, in gems that are never loaded together and so could never diverge
+  # loudly. This is the shared home they already have.
+  #
+  # A class-level instance variable is not visible to a subclass, which is what makes `@limits` on a base class
+  # invisible to the operation that inherits from it. Walking `ancestors` is what turns that into inheritance.
+  # `Class` only, because a module cannot carry one of these declarations.
+  module Declarations
+    private
+      # The first ancestor that set it, or nil. `false` is a value and survives; only nil means unset.
+      def inherited_value(variable)
+        ancestors.grep(Class).each do |ancestor|
+          value = ancestor.instance_variable_get(variable)
+          return value unless value.nil?
+        end
+
+        nil
+      end
+  end
+end

data/lib/hot_cell/descriptors.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "fcntl"
+
+module HotCell
+  # A descriptor, not a path. The cold side opens the file and passes the open descriptor, so no path a
+  # hot side chooses is ever opened by the cold side, and no path the cold side chose is ever visible
+  # to a tool.
+  #
+  # These verify rather than merely tag, and both sides verify. An access mode is fixed at open and
+  # cannot be narrowed afterward, so a cell handed a read-write descriptor as an input cannot correct
+  # it — it can only decline the request.
+  class Descriptor
+    MODES = {
+      Fcntl::O_RDONLY => "read-only",
+      Fcntl::O_WRONLY => "write-only",
+      Fcntl::O_RDWR   => "read-write",
+    }.freeze
+
+    attr_reader :io
+
+    def initialize(io, scratch: nil)
+      @io = io
+      @scratch = scratch
+      verify_regular_file!
+      verify_access_mode!
+      verify_position!
+    end
+
+    def to_io
+      io
+    end
+
+    # The path that reads or writes this descriptor in place, without a copy onto scratch. `/dev/fd/N`
+    # names the open file behind fd N: the worker itself may open it (libvips does), and a spawned tool
+    # sees it too when the worker hands the fd across the exec at the same number — see Operation#run_tool.
+    #
+    # This is what keeps a multi-gigabyte input off a small tmpfs: the descriptor is the caller's own file,
+    # readable at any size, where staging it would be a write and RLIMIT_FSIZE bounds writes. Reopening
+    # `/dev/fd/N` gives a fresh file description at offset zero, so a read here does not disturb the
+    # descriptor the supervisor still holds.
+    def fd_path
+      "/dev/fd/#{io.fileno}"
+    end
+
+    def close
+      io.close unless io.closed?
+    end
+
+    # Whether this descriptor has been given a filename on the worker's own scratch.
+    def staged?
+      !@path.nil?
+    end
+
+    private
+      # The worker hands each descriptor the scratch it may stage onto; the client hands over nothing,
+      # because a filename is the worker's concern and no path the cold side names must ever matter.
+      def scratch_path
+        raise Error, "#{self.class.name} has no scratch, so a path is not a question for this side" if @scratch.nil?
+
+        @scratch.call
+      end
+
+      def verify_access_mode!
+        mode = io.fcntl(Fcntl::F_GETFL) & Fcntl::O_ACCMODE
+        return if mode == self.class::ACCESS_MODE
+
+        raise AccessModeError, "#{self.class.name} needs a #{MODES.fetch(self.class::ACCESS_MODE)} " \
+                               "descriptor, and this one is #{MODES.fetch(mode, "mode #{mode}")}"
+      end
+
+      # O_APPEND is a caller bug of the same shape as handing over a read-write descriptor, and it fails as
+      # quietly: every write lands at the end whatever the cell does, so a conversion is appended to
+      # whatever the file already held and the caller reads its old bytes followed by new ones. Like the
+      # access mode this is fixed at open, so the only thing a cell can do about it is decline.
+      def verify_position!
+        return unless (io.fcntl(Fcntl::F_GETFL) & Fcntl::O_APPEND).positive?
+
+        raise AccessModeError, "#{self.class.name} was opened with O_APPEND, so a conversion would be " \
+                               "appended to what the file already holds rather than becoming its contents"
+      end
+
+      # A pipe as an output can deadlock a single streaming write against a cold side that is not
+      # draining it, and a character device is nobody's conversion.
+      def verify_regular_file!
+        return if io.stat.file?
+
+        raise AccessModeError, "#{self.class.name} needs a regular file, and this one is a #{io.stat.ftype}"
+      end
+  end
+
+  class Input < Descriptor
+    ACCESS_MODE = Fcntl::O_RDONLY
+
+    # Copies the bytes onto the worker's own scratch on the first call and returns the filename. This is the
+    # fallback, for an operation that genuinely needs a real file. Prefer `fd_path`, which reads the
+    # descriptor in place: staging is a write, so RLIMIT_FSIZE bounds it, and an input larger than the
+    # operation's file_size dies here as a permanent `fsize` verdict — a ceiling Rails does not have. The
+    # Active Storage operations all read `fd_path` for exactly that reason; nothing should reach for `path`
+    # without a specific need for a distinct on-disk copy.
+    #
+    # On call rather than up front, so an operation that never asks for a staged path never pays for the copy.
+    def path
+      @path ||= copied_to(scratch_path)
+    end
+
+    private
+      def copied_to(path)
+        File.open(path, "wb") { |file| IO.copy_stream(io, file) }
+        path
+      end
+  end
+
+  class Output < Descriptor
+    ACCESS_MODE = Fcntl::O_WRONLY
+
+    # Names the file the operation is to write, on the first call. Nothing is copied yet: post sends
+    # the file back out through the descriptor, and an operation that writes the descriptor directly
+    # never names one at all.
+    #
+    # `extension` names a suffixed sibling on the same scratch instead, for a producer that picks its
+    # saver from the extension (ImageProcessing) or appends one of its own (pdftoppm). The sibling is
+    # not what post ships: adopt renames it into place.
+    def path(extension: nil)
+      base = (@path ||= scratch_path)
+      extension.nil? ? base : "#{base}.#{extension}"
+    end
+
+    # Renames a staged sibling onto `path`, so post ships it. A sibling the tool never wrote is left
+    # to post's zero-byte accounting.
+    def adopt(staged)
+      File.rename staged, path if File.exist?(staged)
+    end
+
+    # Sends whatever the operation produced back out through the descriptor, and returns the byte count
+    # the cold side can now read. Outputs are posted and flushed before success is reported, so a
+    # caller may read as soon as it sees `ok`.
+    #
+    # Two shapes, and an operation chooses by which path it wrote. A staged output was written to `path` on
+    # scratch and is copied out here; a file that does not exist means the operation wrote nothing, reported
+    # as zero the way a full tmpfs is. An output the operation wrote straight through the descriptor was
+    # never staged, so there is nothing to copy — the bytes are already in the caller's file — and this only
+    # flushes and measures. The direct form leaves partial bytes in the caller's file if the operation
+    # fails mid-write, where the staged form leaves it empty; every operation that writes directly turns a
+    # failure into a refusal the caller acts on rather than reading those bytes as a result.
+    def post
+      if staged?
+        return 0 unless File.exist?(path)
+
+        File.open(path, "rb") { |file| IO.copy_stream(file, io) }.tap { io.flush }
+      else
+        io.flush
+        io.stat.size
+      end
+    end
+  end
+end

data/lib/hot_cell/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module HotCell
+  # What this gem raises when a call is wrong, as distinct from a cell's verdict on a conversion.
+  #
+  # These must be raised outside the client's transport rescue. An application injects its own
+  # exception classes for a cell's verdicts, and if one of those descends from IOError then a bad call
+  # swallowed by the transport rescue comes back as a socket failure and gets retried forever.
+  class Error < StandardError; end
+
+  # A payload or result value JSON cannot carry faithfully. Raised before anything is sent, because
+  # to_json is not a check: it turns a Symbol into a String, a Time into a String, and an arbitrary
+  # object into whatever its own to_json says, all silently and none of it reversible.
+  class SerializationError < Error; end
+
+  # A descriptor offered as an input that is not read-only, or as an output that is not write-only.
+  # An access mode is fixed at open and cannot be narrowed afterward, so this can only be declined.
+  class AccessModeError < Error; end
+
+  # A message that is not what the protocol says it is: unparseable, too long, or missing a field.
+  class MessageError < Error; end
+
+  # Either side configured wrongly. Raised at boot rather than at the first request, because a cell that
+  # cannot hold its limits and a client that cannot classify a failure are both worse discovered in traffic.
+  class ConfigurationError < Error; end
+
+  # A peer that stopped mid-message. Distinct from a cell answering `timeout`, which is a verdict: this is
+  # the caller's own deadline passing with the response incomplete.
+  class ReadTimeout < Error; end
+
+  # A client naming a cell nobody registered.
+  class UnregisteredCell < Error; end
+
+  # A client calling a cell whose socket directory is unset, which means the deployment has not turned this
+  # path on. The caller is the one that knows what to do instead, so this is loud rather than silent.
+  class CellNotConfigured < Error; end
+end

data/lib/hot_cell/failure.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module HotCell
+  # A cell's verdict on a request that did not succeed.
+  #
+  # The message is untrusted and it outlives the request. It comes out of a worker that has just parsed
+  # a hostile file, and Vips::Error#message routinely contains the input filename. Applications store
+  # these as durable blob metadata so they can re-decide later against a newer library, which means an
+  # unscrubbed byte sequence becomes a permanently poisoned row, and an invalid UTF-8 sequence makes a
+  # downstream regex raise ArgumentError instead of answering false.
+  #
+  # So the message is capped and scrubbed here, and that is not only hygiene: a cell that could not
+  # serialize its own error could not answer at all. The client scrubs again on receipt, because
+  # JSON.parse is not a filter — a \uD800 escape parses into an invalid UTF-8 String without complaint.
+  class Failure
+    MAX_MESSAGE_BYTES = 512
+
+    attr_reader :code, :message, :error_class, :cause, :signal
+
+    # 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
+    # `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)
+      @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)
+      @permanent = permanent.nil? ? Codes.permanent?(@code, cause: @cause) : permanent
+    end
+
+    def permanent?
+      @permanent
+    end
+
+    # compact rather than four guards: the constructor puts every one of these through `&.to_s` or
+    # `sanitize`, so each is a String or nil and there is no falsey-but-meaningful value to protect.
+    # `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
+    end
+
+    def to_s
+      [ code, cause, error_class, message ].compact.join(": ")
+    end
+
+    class << self
+      # Builds from either a message String or an Exception. An Exception has to become two wire fields, and
+      # that rule was written out at three call sites across two gems — the worker, the supervisor's control
+      # answer, and the client's transport.
+      def for(code, detail, cause: nil)
+        if detail.is_a?(Exception)
+          new code: code, cause: cause, error_class: detail.class.name, message: detail.message
+        else
+          new code: code, cause: cause, message: detail
+        end
+      end
+
+      # A code this client has never heard of is not permanent. An old client will meet a code added
+      # later, and the harm of the two mistakes is not symmetrical: retrying something permanent costs
+      # some work, while writing down a verdict that was temporary is irreversible.
+      # A `permanent` that is present but not a boolean is derived rather than believed. Truthiness would make
+      # any non-nil value permanent, and permanent is the answer that cannot be taken back — so a garbled
+      # field must not be able to say it.
+      def from_wire(wire)
+        permanent = if [ true, false ].include?(wire[:permanent])
+          wire[:permanent]
+        else
+          Codes.known?(wire[:code]) && Codes.permanent?(wire[:code], cause: wire[:cause])
+        end
+
+        new code: wire[:code], permanent: permanent, cause: wire[:cause], signal: wire[:signal],
+            error_class: wire[:class], message: wire[:message]
+      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)
+        return nil if message.nil?
+
+        String(message).dup.force_encoding(Encoding::UTF_8)
+          .scrub("").byteslice(0, MAX_MESSAGE_BYTES).scrub("")
+      end
+    end
+  end
+end

data/lib/hot_cell/fields.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module HotCell
+  # How a wire message reads its own fields, shared by Request and Response.
+  #
+  # The two had a copy each of the same parse preamble and the same typed-field check, differing only in
+  # whether the error said "request" or "response" — so a fix to the wording landed in one and not the other.
+  #
+  # The includer states its own `noun`. Deriving it from the class name looks tidier and does not work:
+  # Request's singleton defines `name(parsed, key)` for its own String field, which shadows Module#name.
+  module Fields
+    private
+      # Wraps the two errors every parse can produce: a line that is not JSON, and a line that is JSON but
+      # not an object. The block builds the message from the parsed Hash.
+      #
+      # Payload.parse already answers with MessageError however the JSON layer failed, so this only adds
+      # the noun. It rescues around that call alone rather than around the block, because the block's own
+      # field checks raise MessageError too and re-wording those as "not valid JSON" would be a lie.
+      def parse_message(line)
+        parsed = begin
+          Payload.parse(line)
+        rescue MessageError => error
+          raise MessageError, "#{noun} is not valid JSON: #{error.message}"
+        end
+
+        raise MessageError, "#{noun} is not a JSON object" unless parsed.is_a?(Hash)
+
+        yield parsed
+      end
+
+      def object(parsed, key)
+        value = parsed[key]
+        return value if value.is_a?(Hash)
+
+        raise MessageError, "#{noun} #{key} is #{value.inspect} and must be a JSON object"
+      end
+  end
+end

data/lib/hot_cell/naming.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module HotCell
+  # An operation name is namespaced, and the namespace is what stops two operation sets colliding on one
+  # cell. Both sides derive the same default from the same rule, so a client and an operation that were
+  # never written together still agree.
+  #
+  # A trailing Operation is stripped, because the naming convention puts it on the cell-side class and not
+  # on the client — so TransformImage in the application and TransformImageOperation in the cell both
+  # derive "transform_image", the way Rails strips Controller from a controller's route name.
+  #
+  # This runs in one direction only. A name that arrived on the wire is never turned back into a constant:
+  # it is looked up in a registry that only ever holds classes the cell already loaded.
+  module Naming
+    class << self
+      def default_operation_name(klass)
+        if klass.name.nil?
+          raise ConfigurationError, "#{klass.inspect} is anonymous, so it needs an explicit name"
+        end
+
+        *namespaces, base = klass.name.split("::")
+        base = base.delete_suffix("Operation") unless base == "Operation"
+
+        [ *namespaces, base ].map { |part| underscore(part) }.join(".")
+      end
+
+      def underscore(camel)
+        camel.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+    end
+  end
+end

data/lib/hot_cell/payload.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+
+module HotCell
+  # A payload is a JSON object, and the rules are stricter than JSON's in one direction and looser in
+  # another.
+  #
+  # Values must be JSON-native, because to_json is not a check. It serializes a Symbol to a String, a
+  # Time to a String, and an arbitrary object through whatever to_json that object happens to define,
+  # all silently and none of it faithfully. So validate the values, then serialize.
+  #
+  # Keys may be Strings or Symbols, because both serialize to the same JSON string and both arrive
+  # symbolized. `{ format: "png" }` is how a payload is naturally written and must not be rejected.
+  module Payload
+    # A payload sits one level inside the message envelope, so it gets one level less than the line.
+    MAX_DEPTH = MAX_NESTING - 1
+
+    class << self
+      def generate(object, name)
+        validate! object, name
+        JSON.generate object
+      end
+
+      # Keys are deep-symbolized here rather than in an operation, so an operation never has to know
+      # whether to reach for payload[:format] or payload["format"], and a nested hash can be splatted
+      # straight into a library's keyword arguments. Only keys: a Symbol value would not survive the
+      # round trip, which the JSON-native rule already forbids.
+      #
+      # JSON.parse only. Never JSON.load, and never create_additions, both of which instantiate
+      # arbitrary classes named by a json_class key in the document.
+      #
+      # Every way this can fail becomes one named failure, and the catch-all is the point rather than
+      # laziness. Callers used to name what JSON.parse raises, and naming it has now been wrong twice: a
+      # report that was not an object raised TypeError past a rescue for JSON::ParserError, and a key
+      # holding bytes that are not valid UTF-8 raises EncodingError past both. The supervisor reads worker
+      # reports through here inside the loop that enforces every request's deadline, and nothing above it
+      # rescues anything, so each miss is a one-line denial of service against every request in the cell.
+      #
+      # The body is a single JSON.parse call, so this is scoped to "the JSON layer failed" and cannot
+      # swallow a bug in our own code. NoMemoryError is deliberately not caught: it is not a StandardError,
+      # and a document large enough to raise it is the worker's own memory verdict rather than a bad line.
+      def parse(json)
+        JSON.parse json, symbolize_names: true, max_nesting: MAX_NESTING, allow_nan: false,
+                         create_additions: false
+      rescue StandardError => error
+        raise MessageError, "#{error.class}: #{Failure.sanitize(error.message)}"
+      end
+
+      def validate!(object, name)
+        unless object.is_a?(Hash)
+          raise SerializationError, "#{name} is a #{object.class} and must be a Hash"
+        end
+
+        walk object, name, 1
+        object
+      end
+
+      private
+        def walk(value, path, depth)
+          case value
+          when Hash
+            too_deep! path, depth
+            seen = {}
+
+            value.each do |key, nested|
+              unless key.is_a?(String) || key.is_a?(Symbol)
+                raise SerializationError,
+                      "#{path} has a #{key.class} key #{key.inspect}; keys must be String or Symbol"
+              end
+
+              # A Hash holding both :a and "a" is legal Ruby and two distinct keys. JSON has one string key
+              # space, so it serializes to a document with "a" twice, and parsing that back keeps whichever
+              # came last — one of the values is gone and nothing said so. Refused here rather than silently
+              # dropped, because this runs on results too, where the loss would be the caller's data.
+              if (clash = seen[key.to_s])
+                raise SerializationError,
+                      "#{path} has both #{clash.inspect} and #{key.inspect}, which are one key in JSON"
+              end
+              seen[key.to_s] = key
+
+              walk nested, "#{path}[#{key.inspect}]", depth + 1
+            end
+          when Array
+            too_deep! path, depth
+            value.each_with_index { |nested, index| walk nested, "#{path}[#{index}]", depth + 1 }
+          when Float
+            unless value.finite?
+              raise SerializationError, "#{path} is #{value}, which JSON cannot carry"
+            end
+          when String
+            # JSON.generate refuses a String whose bytes are not valid UTF-8, and it refuses it *after* this
+            # has said the structure is fine. In a worker that meant dying with no answer at all, on a
+            # response that had already been decided — so the caller read a closed socket and retried
+            # something that will fail the same way every time. Tools produce these: a filename, or a
+            # line of stderr. Scrub it in the operation if you want it; it is not scrubbed here, because a
+            # result is data the caller acts on rather than a diagnostic.
+            unless value.valid_encoding?
+              raise SerializationError, "#{path} is a String whose bytes are not valid #{value.encoding}"
+            end
+
+            value
+          when Integer, true, false, nil
+            value
+          else
+            raise SerializationError, "#{path} is a #{value.class}, which JSON cannot carry faithfully"
+          end
+        end
+
+        def too_deep!(path, depth)
+          return if depth <= MAX_DEPTH
+          raise SerializationError, "#{path} nests deeper than #{MAX_DEPTH} levels"
+        end
+    end
+  end
+end

data/lib/hot_cell/protocol.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module HotCell
+  # Checked, never negotiated. A cell answers `protocol` to anything else, which is transient rather
+  # than a bug: during a rolling deploy the app moves before the accessory reboots, so every request
+  # mismatches until it does.
+  PROTOCOL_VERSION = 1
+
+  # A request is a control message from the trusted side, and the worker parses it before it has
+  # narrowed to the operation's limits. Capping it is what bounds that parse.
+  MAX_REQUEST_BYTES = 8192
+
+  # A response carries metadata rather than bytes, so this is generous rather than tight.
+  MAX_RESPONSE_BYTES = 65_536
+
+  # The kernel caps SCM_RIGHTS at 253 descriptors per message. Nothing here wants more than a handful.
+  MAX_DESCRIPTORS = 16
+
+  # Nesting depth of a whole message line. Deep symbolization walks the structure, so this is what
+  # bounds the recursion.
+  MAX_NESTING = 8
+
+  # The two operations a cell answers on control.sock rather than work.sock. The names live here because
+  # both sides need them and neither owns them.
+  DESCRIBE = "hotcell.describe"
+  METRICS = "hotcell.metrics"
+  CONTROL_OPERATIONS = [ DESCRIBE, METRICS ].freeze
+end

data/lib/hot_cell/request.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module HotCell
+  # One line of UTF-8 JSON terminated by a newline, sent with a single sendmsg carrying one SCM_RIGHTS
+  # message.
+  #
+  #   {"v":1,"op":"active_storage.transform_image","inputs":1,"outputs":1,"payload":{"format":"png"}}
+  #
+  # Inputs are the leading descriptors and outputs the trailing ones, so two counts are the whole
+  # framing and there is no naming layer to keep in step with an operation.
+  class Request
+    attr_reader :version, :op, :inputs, :outputs, :payload
+
+    def initialize(op:, inputs: 0, outputs: 0, payload: {}, version: PROTOCOL_VERSION)
+      @version = version
+      @op = op
+      @inputs = inputs
+      @outputs = outputs
+      @payload = payload
+
+      verify_descriptor_count!
+    end
+
+    def descriptor_count
+      inputs + outputs
+    end
+
+    def current_version?
+      version == PROTOCOL_VERSION
+    end
+
+    # Next to the predicate it explains, because both sockets answer with it and a caller may well be
+    # grepping for it — the one failure that arrives at a hundred percent during a rolling deploy.
+    def version_mismatch
+      "this cell speaks v#{PROTOCOL_VERSION} and the request is v#{version}"
+    end
+
+    def to_line
+      Payload.validate! payload, "payload"
+
+      line = JSON.generate({ v: version, op: op, inputs: inputs, outputs: outputs, payload: payload }) << "\n"
+      if line.bytesize > MAX_REQUEST_BYTES
+        raise MessageError, "request is #{line.bytesize} bytes, over the #{MAX_REQUEST_BYTES} byte limit"
+      end
+
+      line
+    end
+
+    class << self
+      include Fields
+
+      def noun
+        "request"
+      end
+
+      def parse(line)
+        parse_message(line) do |parsed|
+          new version: integer(parsed, :v), op: name(parsed, :op), inputs: count(parsed, :inputs),
+              outputs: count(parsed, :outputs), payload: object(parsed, :payload)
+        end
+      end
+
+      private
+        def integer(parsed, key)
+          value = parsed[key]
+          return value if value.is_a?(Integer)
+
+          raise MessageError, "request #{key} is #{value.inspect} and must be an Integer"
+        end
+
+        def count(parsed, key)
+          integer(parsed, key).tap do |value|
+            raise MessageError, "request #{key} is #{value} and must not be negative" if value.negative?
+          end
+        end
+
+        def name(parsed, key)
+          value = parsed[key]
+          return value if value.is_a?(String) && !value.empty?
+
+          raise MessageError, "request #{key} is #{value.inspect} and must be a non-empty String"
+        end
+    end
+
+    private
+      def verify_descriptor_count!
+        if descriptor_count > MAX_DESCRIPTORS
+          raise MessageError, "request wants #{descriptor_count} descriptors, over the #{MAX_DESCRIPTORS} limit"
+        end
+      end
+  end
+end

data/lib/hot_cell/response.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module HotCell
+  # One line of JSON. Outputs are posted and flushed before success is reported, so the cold side may
+  # read as soon as it sees `ok`.
+  #
+  # `timing` is present on every response, success or failure, and it is also the cell's tracing
+  # channel. A cell cannot reach a trace collector, so anything it knows about its own internals
+  # travels back here or not at all. An operation may add its own keys, and a client should treat the
+  # map as open.
+  class Response
+    attr_reader :version, :result, :failure, :timing
+
+    class << self
+      include Fields
+
+      def noun
+        "response"
+      end
+
+      def ok(result: {}, timing: {})
+        new result: result, timing: timing
+      end
+
+      def failed(failure, timing: {})
+        new failure: failure, timing: timing
+      end
+
+      # `ok` has to be the boolean it says it is rather than anything truthy. This is the field the whole
+      # taxonomy turns on, and Ruby's truthiness would read `"false"`, `0` and `[]` as success — so a
+      # malformed or hostile response could turn a failure into an `ok` carrying no result at all.
+      #
+      # **Accepted risk.** Nothing inside `result` is checked, and a compromised cell chooses all of it.
+      # `Payload.validate!` is not run on the way in, so a value JSON can carry but Ruby cannot serialize
+      # again reaches the caller — `1e400` parses to `Float::INFINITY`, and an application that writes a
+      # result to a JSON column raises there rather than here. The premise is that a result is data the
+      # caller acts on and only the caller knows its shape, so the framework has no rule to apply and a
+      # client with a specific expectation states it itself. `ok` is the exception because the taxonomy
+      # turns on it and every caller depends on it equally.
+      def parse(line)
+        parse_message(line) do |parsed|
+          ok = parsed[:ok]
+          unless ok == true || ok == false
+            raise MessageError, "response ok is #{ok.inspect} and must be true or false"
+          end
+
+          timing = parsed[:timing].is_a?(Hash) ? parsed[:timing] : {}
+
+          if ok
+            new version: parsed[:v], result: object(parsed, :result), timing: timing
+          else
+            new version: parsed[:v], failure: Failure.from_wire(object(parsed, :error)), timing: timing
+          end
+        end
+      end
+    end
+
+    def initialize(result: nil, failure: nil, timing: {}, version: PROTOCOL_VERSION)
+      @result = result
+      @failure = failure
+      @timing = timing
+      @version = version
+    end
+
+    def ok?
+      failure.nil?
+    end
+
+    def to_line
+      body = { v: version, ok: ok? }
+      if ok?
+        body[:result] = Payload.validate!(result, "result")
+      else
+        body[:error] = failure.to_h
+      end
+      body[:timing] = Payload.validate!(timing, "timing")
+
+      line = JSON.generate(body) << "\n"
+      if line.bytesize > MAX_RESPONSE_BYTES
+        raise MessageError, "response is #{line.bytesize} bytes, over the #{MAX_RESPONSE_BYTES} byte limit"
+      end
+
+      line
+    end
+  end
+end

data/lib/hot_cell/test_support.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module HotCell
+  # Fixtures and waits for the suites of all three gems, shipped rather than copied.
+  #
+  # Same reasoning as `hot_cell/test_cell.rb` shipping from hotcell-server: a helper every consumer needs is
+  # one every consumer should get, not one each writes again. Before this, `with_file` had three
+  # byte-identical copies, `wait_until` had two — one of them inside a test file rather than a helper — and
+  # the monotonic clock was hand-rolled six times in code that already loads HotCell::Clock.
+  #
+  # It lives in hotcell-core because that is the gem all three load. Requiring it is opt-in, so nothing here
+  # reaches a production graph unless a suite asks for it.
+  #
+  # Include into a Minitest::Test subclass; `skip` and `flunk` are called on the including test.
+  module TestSupport
+    private
+      # Descriptors have to be regular files, so every fixture is a real file on disk.
+      def with_file(contents = "")
+        Tempfile.create([ "hotcell", ".bin" ], binmode: true) do |file|
+          file.write contents
+          file.flush
+          yield file.path
+        end
+      end
+
+      # A source and a destination, which is the shape of most requests.
+      def with_files(contents = "source bytes")
+        with_file(contents) { |source| with_file { |destination| yield source, destination } }
+      end
+
+      def reading(path, &block)
+        File.open path, "rb", &block
+      end
+
+      def writing(path, &block)
+        File.open path, "wb", &block
+      end
+
+      def updating(path, &block)
+        File.open path, "r+b", &block
+      end
+
+      def open_descriptors
+        skip "counting open descriptors needs Linux" unless File.directory?("/proc/self/fd")
+
+        Dir.children("/proc/self/fd").size
+      end
+
+      # True while the process exists and is not a zombie. A killed process lingers as a zombie until its
+      # parent reaps it, and a zombie is dead for a caller watching for a sweep. The state is the first
+      # token after the final `)` of /proc/<pid>/stat, which is where the comm field ends.
+      # ESRCH alongside ENOENT: the entry can be torn down between the open and the read, and a caller
+      # polling for a kill is exactly who reads during the teardown.
+      def process_running?(pid)
+        state = File.read("/proc/#{pid}/stat")[/\)\s+(\S)/, 1]
+        !state.nil? && state != "Z"
+      rescue Errno::ENOENT, Errno::ESRCH
+        false
+      end
+
+      # A cell writes its log and removes its scratch after it has answered, so a few properties are
+      # genuinely asynchronous with respect to the caller. Bounded polling says so; a sleep would not.
+      def wait_until(within: 5, what: "the condition")
+        deadline = Clock.now + within
+
+        until yield
+          flunk "#{what} did not happen within #{within}s" if Clock.now > deadline
+
+          sleep 0.01
+        end
+      end
+
+      def elapsed
+        at = Clock.now
+        yield
+        Clock.now - at
+      end
+  end
+end

data/lib/hotcell-core.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem named "hotcell-core" as "hotcell-core", then as "hotcell/core". This gem
+# uses neither path, because hot_cell/ is what yields the HotCell constant under the default inflection.
+# Without this file, `gem "hotcell-core"` in a Gemfile silently loads nothing at all.
+require "hot_cell/core"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotcell-core
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Dalessio
@@ -9,16 +9,44 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: To be released soon, secure sidecar for Rails
+description: |
+  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: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/hot_cell/clock.rb
+- lib/hot_cell/codes.rb
+- lib/hot_cell/connection.rb
+- lib/hot_cell/core.rb
+- lib/hot_cell/core/version.rb
+- lib/hot_cell/declarations.rb
+- lib/hot_cell/descriptors.rb
+- lib/hot_cell/errors.rb
+- lib/hot_cell/failure.rb
+- lib/hot_cell/fields.rb
+- lib/hot_cell/naming.rb
+- lib/hot_cell/payload.rb
+- lib/hot_cell/protocol.rb
+- lib/hot_cell/request.rb
+- lib/hot_cell/response.rb
+- lib/hot_cell/test_support.rb
+- lib/hotcell-core.rb
+homepage: https://github.com/basecamp/hotcell
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/basecamp/hotcell
+  source_code_uri: https://github.com/basecamp/hotcell/tree/v0.2.0/hotcell-core
+  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: []
 require_paths:
 - lib
@@ -26,7 +54,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -35,5 +63,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: To be released soon, secure sidecar for Rails
+summary: The wire protocol shared by both sides of a HotCell.
 test_files: []