ace-lab 0.5.2 → 0.7.0

data/lib/ace/lab/molecules/ordinary_admission_resolver.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "service_policy"
+
+module Ace
+  module Lab
+    module Molecules
+      # The scoped ordinary-merge decision/admission resolver (spec 8x3.t.xz9.4,
+      # execution clauses). The deployment-owned YAML authorization file remains
+      # the sole source of truth; this resolver only makes the exact root
+      # authorizations natively executable inside the receiver: one per-request
+      # authorization selector resolves to a typed decision within the closed
+      # refusal-code family — or it refuses. Scoping rules:
+      #
+      # - only `operation: merge` decisions of the ordinary shape resolve;
+      #   anything else (missing reference, shape mismatch, non-merge
+      #   operation, any binding mismatch, expiry) is a typed
+      #   `ordinary_merge_authorization_invalid` decision;
+      # - exact binding match on every closed key; there are NO wildcards,
+      #   defaults, prefix grants or broad grants of any kind — a decision
+      #   authorizes exactly one bound request and nothing else;
+      # - expiry bounds the decision itself.
+      #
+      # Per-request refresh (spec 8x3.t.xz9.5 integration handoff): a
+      # long-lived receiver would otherwise decide every sequential candidate
+      # against its boot-time snapshot of the authorization document. When a
+      # trusted path is installed, every decision re-reads the document
+      # through the trusted loader and resolves against the FRESH grants —
+      # a root-revoked or expired decision fails closed at the next request
+      # without any receiver restart. The refresh is scoped: it reloads and
+      # re-validates the exact-request grant only; it never broadens
+      # authorization beyond the resolved reference.
+      class OrdinaryAdmissionResolver
+        BINDING_KEYS = ServicePolicy::ORDINARY_BINDING_KEYS.freeze
+        DECISION_KEYS = ServicePolicy::ORDINARY_AUTHORIZATION_KEYS.freeze
+        OPERATION = "merge"
+
+        Decision = Struct.new(:authorized?, :decision, :code, :message, keyword_init: true)
+
+        # @param policy_document [Hash] boot-time trusted document (the
+        #   configuration digest is derived from it once, upstream)
+        # @param path [String, nil] trusted policy path to re-read per decision
+        # @param loader [Proc, nil] trusted reader (default: GrantResolver);
+        #   the only override point, for non-privileged test documents
+        def initialize(policy_document, path: nil, loader: nil)
+          unless policy_document.is_a?(Hash) && policy_document["authorizations"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "trusted policy document must contain an authorizations mapping"
+          end
+          @authorizations = policy_document.fetch("authorizations")
+          @path = path
+          @loader = loader || ->(trusted_path) { GrantResolver.trusted_document(trusted_path) }
+          freeze
+        end
+
+        # Resolve one authorization selector against the exact ordinary merge
+        # request binding. Returns a typed Decision; `authorized?` is true only
+        # for an exact, unexpired, ordinary-merge-shaped match.
+        def decide(reference, binding)
+          authorizations = current_authorizations
+          unless reference.is_a?(String) && reference.match?(ServicePolicy::ID)
+            return refuse("invalid authorization reference")
+          end
+          unless binding.is_a?(Hash) && binding.fetch("operation", nil) == OPERATION
+            return refuse("only the ordinary merge operation is resolvable")
+          end
+          decision = authorizations[reference]
+          return refuse("authorization reference is unresolved") unless decision.is_a?(Hash)
+          unless DECISION_KEYS.all? { |key| decision.key?(key) }
+            return refuse("authorization reference is not an ordinary merge decision")
+          end
+          unless decision.fetch("operation") == OPERATION
+            return refuse("authorization does not cover the ordinary merge operation")
+          end
+          mismatch = BINDING_KEYS.find { |key| decision.fetch(key) != binding.fetch(key, nil) }
+          return refuse("authorization does not match the exact ordinary merge request") if mismatch
+          begin
+            expired = Time.iso8601(decision.fetch("expires_at").to_s) <= Time.now.utc
+          rescue ArgumentError
+            return refuse("authorization decision has an invalid expiry")
+          end
+          return refuse("authorization has expired") if expired
+          Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
+        end
+
+        private
+
+        # The authorizations mapping the CURRENT decision resolves against:
+        # the boot snapshot when no trusted path is installed, otherwise the
+        # freshly re-read document. A failed trusted re-read fails closed
+        # (InvalidConfigurationError — the unavailable family), never falls
+        # back to the stale snapshot.
+        def current_authorizations
+          return @authorizations unless @path
+          document = @loader.call(@path)
+          unless document.is_a?(Hash) && document["authorizations"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "invalid lab configuration: trusted authorization refresh at #{@path} " \
+              "did not yield an authorizations mapping"
+          end
+          document.fetch("authorizations")
+        end
+
+        def refuse(message)
+          Decision.new(authorized?: false, decision: nil,
+            code: "ordinary_merge_authorization_invalid", message: message)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_ff_merge.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Lab
+    module Molecules
+      # The fixed merge method executor (spec 8x3.t.xz9.4, merge-method
+      # contract). The closed request schema admits literal `method=merge`;
+      # the installed executor gives that method FAST-FORWARD-ONLY semantics:
+      # the candidate head must be a descendant of the current base head.
+      # A non-fast-forwardable candidate is NOT merged silently and never
+      # falls back to a merge commit — it reports `:non_fast_forward` so the
+      # receiver answers in the moved-target/needs-rebase refusal family.
+      # The mutation itself is one atomic compare-and-swap on the base ref
+      # (`git update-ref <base> <candidate> <expected>`), so concurrent
+      # writers can never both move the ref: the loser provably performed
+      # no effect. Under this strategy the resulting base head equals the
+      # candidate head, and the receipt joins `merge_commit ==
+      # resulting_target_head == merged_candidate_head` — that join is the
+      # receipt's fast-forward proof. Any future non-ff strategy is a
+      # separate reviewed contract extension, never implicit.
+      class OrdinaryFfMerge
+        STRATEGY = "ff"
+
+        Result = Struct.new(:outcome, :resulting_head, :previous_head, :reason, keyword_init: true)
+
+        def initialize(repo_path:, base_ref:)
+          unless repo_path.is_a?(String) && repo_path.start_with?("/") &&
+              base_ref.is_a?(String) && base_ref.start_with?("refs/")
+            raise ArgumentError, "ordinary ff merge needs an absolute repo path and a full base ref"
+          end
+          @repo_path = repo_path
+          @base_ref = base_ref
+        end
+
+        def base_head
+          out, stderr, status = git("rev-parse", @base_ref)
+          return out.strip if status.success?
+          raise GitUnavailable, "base ref #{@base_ref} is unreadable: #{stderr.strip[0, 200]}"
+        end
+
+        def candidate_commit?(sha)
+          git("cat-file", "-e", "#{sha}^{commit}").last.success?
+        end
+
+        # True only when the candidate is a descendant of (or equal to) the
+        # current base head — the fast-forward precondition.
+        def fast_forwardable?(candidate_head)
+          git("merge-base", "--is-ancestor", @base_ref, candidate_head).last.success?
+        end
+
+        # The single effect: one compare-and-swap ref update. Returns a
+        # Result with outcome `:merged`, `:already_merged`, or `:race_lost`
+        # (the expected head moved before the swap — provably no effect from
+        # this invocation). Raises GitUnavailable when git itself fails.
+        def merge!(candidate_head, expected_head)
+          current = base_head
+          return Result.new(outcome: :already_merged, resulting_head: current,
+            previous_head: current, reason: nil) if current == candidate_head
+          unless current == expected_head
+            return Result.new(outcome: :race_lost, resulting_head: current,
+              previous_head: current, reason: "base head moved before the swap")
+          end
+          out, stderr, status = git("update-ref", @base_ref, candidate_head, expected_head)
+          unless status.success?
+            return Result.new(outcome: :race_lost, resulting_head: base_head,
+              previous_head: base_head, reason: "compare-and-swap lost: #{stderr.strip[0, 200]}")
+          end
+          Result.new(outcome: :merged, resulting_head: candidate_head,
+            previous_head: expected_head, reason: nil)
+        end
+
+        class GitUnavailable < ::StandardError; end
+
+        private
+
+        def git(*argv)
+          Open3.capture3("git", *argv, chdir: @repo_path)
+        rescue Errno::ENOENT => e
+          raise GitUnavailable, "git is unavailable: #{e.class}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_listener.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require_relative "../errors"
+require_relative "ordinary_socket"
+
+module Ace
+  module Lab
+    module Molecules
+      # The ordinary receiver's serve-side transport (spec 8x3.t.xz9.4 serve
+      # entrypoint). Binds the configured unix socket and answers the exact
+      # framed protocol the OrdinarySocket client speaks: one bounded JSON
+      # document each way behind the shared handshake line. Authentication is
+      # MUTUAL through SO_PEERCRED: every connection's peer UID must equal
+      # the configured producer principal UID, and the listener itself runs
+      # as the configured receiver UID — the identity the client verifies on
+      # its side. Every identity, framing, deadline or parse failure is
+      # fail-closed: the peer receives the closed refusal envelope (or the
+      # connection closes) and nothing is ever dispatched. This is not an
+      # HTTP transport and there is no cross-VM fallback.
+      class OrdinaryListener
+        HANDSHAKE = OrdinarySocket::HANDSHAKE
+        LIMIT = OrdinarySocket::LIMIT
+        DEADLINE_SECONDS = 30
+
+        def initialize(socket_path:, peer_uid:, handler:, lock_path: nil, logger: nil)
+          unless socket_path.is_a?(String) && socket_path.start_with?("/") &&
+              peer_uid.is_a?(Integer) && peer_uid >= 0 && handler.respond_to?(:call)
+            raise ArgumentError, "ordinary listener needs an absolute socket path, a peer uid and a handler"
+          end
+          @socket_path = socket_path
+          @peer_uid = peer_uid
+          @handler = handler
+          @lock_path = lock_path || "#{@socket_path}.lock"
+          @logger = logger
+          @stopping = false
+        end
+
+        # Serve until #stop. Excludes a second listener through one owned
+        # lock file, removes only its own stale endpoint, and always removes
+        # the endpoint it created.
+        def serve
+          acquire_lock!
+          remove_stale_endpoint!
+          @listener = UNIXServer.new(@socket_path)
+          File.chmod(0o600, @socket_path)
+          @endpoint_identity = File.stat(@socket_path)
+          until @stopping
+            socket = @listener.accept
+            serve_connection(socket)
+          end
+        rescue IOError, Errno::EBADF
+          raise unless @stopping
+        ensure
+          @listener&.close
+          remove_owned_endpoint!
+          @lock&.flock(File::LOCK_UN)
+          @lock&.close
+        end
+
+        def stop
+          @stopping = true
+          @listener&.close
+        rescue IOError
+          nil
+        end
+
+        # One bounded connection: verify the peer identity, read one framed
+        # request, answer one framed envelope, close. Fail-closed on every
+        # violation; a dispatch never happens from an unverified frame.
+        def serve_connection(socket)
+          deadline = Time.now.utc + DEADLINE_SECONDS
+          begin
+            verify_peer!(socket)
+            submission = read_request!(socket, deadline)
+            response = @handler.call(submission)
+            write_response!(socket, response, deadline)
+            if response.is_a?(Hash) && response["status"] == "ok" && @handler.respond_to?(:execute)
+              begin
+                # The durable acknowledgment is already on the wire; the
+                # execution lifetime belongs to the canonical record, not
+                # the short connection. A lost lifecycle stays pending or
+                # uncertain and reconciles by the original reference.
+                @handler.execute(response.dig("data", "request_id"))
+              rescue StandardError
+                nil
+              end
+            end
+          rescue OrdinaryRefused => e
+            write_response!(socket, e.envelope, deadline)
+          rescue OrdinaryListenerError
+            # Fail closed without a fabricated envelope; the client classifies
+            # a lost/unreadable response as ordinary_merge_unavailable.
+            nil
+          rescue StandardError
+            write_response!(socket, refusal_envelope("ordinary_merge_unavailable",
+              "receiver failed to handle the request"), deadline)
+          ensure
+            begin
+              socket.close
+            rescue IOError
+              nil
+            end
+          end
+        end
+
+        class OrdinaryListenerError < ::StandardError; end
+
+        # A verified-connection refusal that still carries a closed envelope.
+        class OrdinaryRefused < OrdinaryListenerError
+          attr_reader :envelope
+
+          def initialize(envelope)
+            @envelope = envelope
+            super(envelope.dig("error", "message").to_s)
+          end
+        end
+
+        private
+
+        # Mutual half of SO_PEERCRED: the connecting process must run as the
+        # configured producer principal UID. Anything else is refused before
+        # one byte of request is read.
+        def verify_peer!(socket)
+          credentials = socket.getsockopt(:SOCKET, :PEERCRED)
+          _peer_pid, peer_uid, = credentials.unpack("L3")
+          return if peer_uid == @peer_uid
+          raise OrdinaryRefused, refusal_envelope("ordinary_merge_unauthenticated",
+            "connecting principal is not the configured ordinary overseer")
+        rescue SystemCallError, IOError
+          raise OrdinaryListenerError, "peer credentials are unavailable"
+        end
+
+        def read_request!(socket, deadline)
+          header = read_line!(socket, deadline)
+          match = /\A#{Regexp.escape(HANDSHAKE)} (\d{1,5})\n\z/o.match(header)
+          raise OrdinaryListenerError, "request header is invalid" unless match
+          length = Integer(match[1])
+          raise OrdinaryListenerError, "request exceeds the wire bound" if length > LIMIT
+          payload = read_exact!(socket, length, deadline)
+          JSON.parse(payload, allow_duplicate_key: false, create_additions: false, max_nesting: 16)
+        rescue JSON::ParserError
+          raise OrdinaryRefused, refusal_envelope("ordinary_merge_invalid_request",
+            "request document is not valid JSON")
+        end
+
+        def write_response!(socket, response, deadline)
+          payload = JSON.generate(response)
+          raise OrdinaryListenerError, "response exceeds the wire bound" if payload.bytesize > LIMIT
+          frame = "#{HANDSHAKE} #{payload.bytesize}\n#{payload}"
+          written = 0
+          while written < frame.bytesize
+            raise OrdinaryListenerError, "response write deadline expired" if Time.now.utc >= deadline
+            begin
+              written += socket.write_nonblock(frame.byteslice(written..))
+            rescue IO::WaitWritable
+              socket.wait_writable(remaining!(deadline)) or
+                raise OrdinaryListenerError, "response write deadline expired"
+            end
+          end
+        rescue JSON::GeneratorError
+          raise OrdinaryListenerError, "response is not serializable"
+        end
+
+        def refusal_envelope(code, message)
+          {"status" => "error", "error" => {
+            "schema" => "ace.lab.service.ordinary-merge-refusal/v1",
+            "code" => code,
+            "message" => message.to_s.scrub.gsub(/\s+/, " ").strip[0, 512],
+            "request_id" => "unknown",
+            "input_digest" => nil
+          }}
+        end
+
+        def read_line!(socket, deadline)
+          line = +""
+          until line.end_with?("\n")
+            raise OrdinaryListenerError, "request header is unbounded" if line.bytesize > 128
+            line << read_exact!(socket, 1, deadline)
+          end
+          line
+        end
+
+        def read_exact!(socket, length, deadline)
+          buffer = +""
+          while buffer.bytesize < length
+            raise OrdinaryListenerError, "request read deadline expired" if Time.now.utc >= deadline
+            begin
+              chunk = socket.read_nonblock(length - buffer.bytesize)
+              raise OrdinaryListenerError, "peer closed the connection" if chunk.nil?
+              buffer << chunk
+            rescue IO::WaitReadable
+              socket.wait_readable(remaining!(deadline)) or
+                raise OrdinaryListenerError, "request read deadline expired"
+            end
+          end
+          buffer
+        end
+
+        def remaining!(deadline)
+          left = deadline - Time.now.utc
+          raise OrdinaryListenerError, "connection deadline expired" if left <= 0
+          left
+        end
+
+        def acquire_lock!
+          @lock = File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+          stat = @lock.stat
+          unless stat.file? && stat.uid == Process.uid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise Ace::Lab::InvalidConfigurationError, "receiver listener lock differs"
+          end
+          unless @lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise Ace::Lab::InvalidConfigurationError, "receiver listener already active"
+          end
+        end
+
+        def remove_stale_endpoint!
+          stat = File.lstat(@socket_path)
+          unless stat.socket? && stat.uid == Process.uid
+            raise Ace::Lab::InvalidConfigurationError, "receiver endpoint differs"
+          end
+          File.unlink(@socket_path)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def remove_owned_endpoint!
+          return unless @endpoint_identity
+          stat = File.stat(@socket_path)
+          File.unlink(@socket_path) if stat.socket? && stat.ino == @endpoint_identity.ino
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_receiver_config.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../errors"
+require_relative "service_policy"
+
+module Ace
+  module Lab
+    module Molecules
+      # Project-scoped, explicitly filed receiver configuration (spec
+      # 8x3.t.xz9.4 execution clauses). The host owns the file, its
+      # placement, its credentials and its deployment; this loader only
+      # validates the exact closed shape and fails closed on anything else.
+      # It invents no credential and accepts no caller-selected endpoint:
+      # every value comes from one explicit deployment-owned YAML file.
+      class OrdinaryReceiverConfig
+        KEYS = %w[project receiver_id socket_path receiver_uid principal principal_uid
+          repo_path policy_path execution_identity].freeze
+        IDENTITY_KEYS = %w[checkout_id worktree_id branch].freeze
+        ID = ServicePolicy::ID
+
+        def self.load(path)
+          raise Ace::Lab::InvalidConfigurationError, "receiver config path is required" unless path.is_a?(String) && !path.empty?
+          document = YAML.safe_load_file(path, permitted_classes: [Date], aliases: false)
+          new(document, source: path)
+        rescue Errno::ENOENT, Errno::EACCES, Psych::Exception
+          raise Ace::Lab::InvalidConfigurationError, "receiver configuration is unreadable: #{path}"
+        end
+
+        attr_reader :project, :receiver_id, :socket_path, :receiver_uid, :principal,
+          :principal_uid, :repo_path, :policy_path, :execution_identity, :source
+
+        def initialize(document, source: nil)
+          unless document.is_a?(Hash) && (document.keys - KEYS).empty? &&
+              (KEYS - document.keys).empty?
+            raise Ace::Lab::InvalidConfigurationError,
+              "receiver configuration must contain exactly: #{KEYS.join(', ')}"
+          end
+          @source = source
+          @project = string!(document.fetch("project"), "project")
+          @receiver_id = string!(document.fetch("receiver_id"), "receiver_id")
+          @principal = string!(document.fetch("principal"), "principal")
+          @socket_path = absolute!(document.fetch("socket_path"), "socket_path")
+          @repo_path = absolute!(document.fetch("repo_path"), "repo_path")
+          @policy_path = absolute!(document.fetch("policy_path"), "policy_path")
+          @receiver_uid = uid!(document.fetch("receiver_uid"), "receiver_uid")
+          @principal_uid = uid!(document.fetch("principal_uid"), "principal_uid")
+          identity = document.fetch("execution_identity")
+          unless identity.is_a?(Hash) && (identity.keys - IDENTITY_KEYS).empty? &&
+              IDENTITY_KEYS.all? { |key| identity[key].is_a?(String) && !identity[key].empty? }
+            raise Ace::Lab::InvalidConfigurationError,
+              "receiver execution_identity is incomplete"
+          end
+          @execution_identity = IDENTITY_KEYS.to_h { |key| [key, identity.fetch(key)] }.freeze
+          unless @repo_path.start_with?("/") && File.directory?(@repo_path)
+            raise Ace::Lab::InvalidConfigurationError, "receiver repo_path is not a directory"
+          end
+          freeze
+        end
+
+        private
+
+        def string!(value, name)
+          unless value.is_a?(String) && !value.empty? && value.length <= 256 && value.match?(ID)
+            raise Ace::Lab::InvalidConfigurationError, "receiver #{name} is invalid"
+          end
+          value
+        end
+
+        def absolute!(value, name)
+          unless value.is_a?(String) && value.start_with?("/") && value.length <= 1024
+            raise Ace::Lab::InvalidConfigurationError, "receiver #{name} must be an absolute path"
+          end
+          value
+        end
+
+        def uid!(value, name)
+          unless value.is_a?(Integer) && value >= 0
+            raise Ace::Lab::InvalidConfigurationError, "receiver #{name} must be a non-negative integer"
+          end
+          value
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_socket.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+module Ace
+  module Lab
+    module Molecules
+      # Admission transport between the ordinary fixed merge producer and the
+      # installed ordinary receiver: one bounded JSON document each way over
+      # a configured unix stream socket with a fixed deadline. Authentication
+      # is mutual through SO_PEERCRED — the producer verifies the receiver's
+      # configured UID and transmits the verified local caller identity, so
+      # no caller-selected credential, token or endpoint exists. This is not
+      # an HTTP transport; a lost or unauthenticated response is a
+      # caller-side blocker (ordinary_merge_unavailable), never a refusal.
+      class OrdinarySocket
+        LIMIT = 16_384
+        HANDSHAKE = "ace-lab/ordinary-merge/v1"
+
+        # @param socket_path [String] installed receiver endpoint (configuration)
+        # @param receiver_uid [Integer] the only UID the receiver may run as
+        # @param deadline [Time] absolute deadline for connect/write/read
+        def initialize(socket_path:, receiver_uid:, deadline: Time.now.utc + 30)
+          @socket_path = socket_path
+          @receiver_uid = receiver_uid
+          @deadline = deadline
+        end
+
+        # Submit one bounded request document; returns the parsed response
+        # document. Any framing, deadline or identity failure raises
+        # OrdinaryUnavailable so the producer can classify the blocker.
+        def submit(document)
+          payload = JSON.generate(document)
+          raise OrdinaryUnavailable, "request document exceeds the wire bound" if payload.bytesize > LIMIT
+          socket = Socket.new(:UNIX, :STREAM, 0)
+          begin
+            socket.connect(Addrinfo.unix(@socket_path))
+            verify_peer!(socket)
+            write_all!(socket, "#{HANDSHAKE} #{payload.bytesize}\n#{payload}")
+            response = read_response!(socket)
+          rescue OrdinaryUnavailable
+            raise
+          rescue SystemCallError, IOError => e
+            raise OrdinaryUnavailable, "receiver transport failed: #{e.class}"
+          ensure
+            begin
+              socket.close
+            rescue IOError
+              nil
+            end
+          end
+          response
+        end
+
+        class OrdinaryUnavailable < ::StandardError; end
+
+        private
+
+        def verify_peer!(socket)
+          credentials = socket.getsockopt(:SOCKET, :PEERCRED)
+          # struct ucred is {pid, uid, gid} on Linux; the producer binds the
+          # receiver to its installed UID and nothing else.
+          _peer_pid, peer_uid, = credentials.unpack("L3")
+          return if peer_uid == @receiver_uid
+          raise OrdinaryUnavailable, "receiver endpoint identity is not the installed receiver"
+        end
+
+        def write_all!(socket, bytes)
+          written = 0
+          while written < bytes.bytesize
+            begin
+              raise OrdinaryUnavailable, "receiver write deadline expired" if expired?
+              written += socket.write_nonblock(bytes.byteslice(written..))
+            rescue IO::WaitWritable
+              socket.wait_writable(remaining!) or raise OrdinaryUnavailable, "receiver write deadline expired"
+            end
+          end
+        end
+
+        def read_response!(socket)
+          header = read_line!(socket)
+          match = /\A#{Regexp.escape(HANDSHAKE)} (\d{1,5})\n\z/o.match(header)
+          raise OrdinaryUnavailable, "receiver response header is invalid" unless match
+          length = Integer(match[1])
+          raise OrdinaryUnavailable, "receiver response exceeds the wire bound" if length > LIMIT
+          body = read_exact!(socket, length)
+          JSON.parse(body, allow_duplicate_key: false, create_additions: false, max_nesting: 16)
+        rescue JSON::ParserError
+          raise OrdinaryUnavailable, "receiver response is not valid JSON"
+        end
+
+        def read_line!(socket)
+          line = +""
+          until line.end_with?("\n")
+            raise OrdinaryUnavailable, "receiver response header is unbounded" if line.bytesize > 128
+            line << read_exact!(socket, 1)
+          end
+          line
+        end
+
+        def read_exact!(socket, length)
+          buffer = +""
+          while buffer.bytesize < length
+            begin
+              raise OrdinaryUnavailable, "receiver read deadline expired" if expired?
+              chunk = socket.read_nonblock(length - buffer.bytesize)
+              raise OrdinaryUnavailable, "receiver closed the connection" if chunk.nil?
+              buffer << chunk
+            rescue IO::WaitReadable
+              socket.wait_readable(remaining!) or raise OrdinaryUnavailable, "receiver read deadline expired"
+            end
+          end
+          buffer
+        end
+
+        def expired?
+          Time.now.utc >= @deadline
+        end
+
+        def remaining!
+          left = @deadline - Time.now.utc
+          raise OrdinaryUnavailable, "receiver deadline expired" if left <= 0
+          left
+        end
+      end
+    end
+  end
+end